feat(api): purge media through the controller edge api (#3454)

fluxer_docs/src/content/docs/operator/configuration.mdx

@@ -1218,11 +1218,11 @@ Default empty. The YouTube Data API key. Also read by `unfurl`, which accepts `Y
 
 #### `FLUXER_CACHE_PURGE_ADAPTER`
 
-Default `none`. How cached copies of deleted or replaced media are purged. `none` or `http`. Anything else fails startup. With `none`, nothing is queued or sent.
+Default `none`. How cached copies of deleted or replaced media are purged. `none`, `http` or `controller`. Anything else fails startup. With `none`, nothing is queued or sent.
 
 #### `FLUXER_CACHE_PURGE_HTTP_ENDPOINT`
 
-Default empty. Required when the adapter is `http`. Must be an absolute `http` or `https` URL without credentials, or startup fails. While purges are queued, the worker posts JSON `{"exact": [...], "prefix": [...]}` here every 10 seconds. Redirects are not followed. Any 2xx marks the batch done. Your endpoint then purges those URLs from every proxy that caches media. A `400` or `422` makes the worker resend each URL alone, and a URL refused alone moves to the `cache_purge:rejected` key. Any other failure is retried on a later run.
+Default empty. Required when the adapter is `http`. Must be an absolute `http` or `https` URL without credentials, or startup fails. While purges are queued, the worker posts JSON `{"prefixes": [...]}` here every 10 seconds, each a media URL prefix without its scheme. Redirects are not followed. Any 2xx marks the batch done. Your endpoint then purges every cached URL under those prefixes from each proxy that caches media. A `400` or `422` moves the batch to the `cache_purge:rejected` key. Any other failure is retried on a later run.
 
 #### `FLUXER_CACHE_PURGE_HTTP_TOKEN`
 
@@ -1232,6 +1232,18 @@ Default empty. The bearer token sent in the `Authorization` header of each purge
 
 Default `10000`. Purge request timeout. Accepts 1000 to 10000. The range is checked only when the adapter is `http`.
 
+#### `FLUXER_CACHE_PURGE_CONTROLLER_ENDPOINT`
+
+Default empty. Required when the adapter is `controller`. The purge URL of the Controller edge site that serves your media, in the form `https://<controller host>/v1/orgs/<org id>/sites/<site id>/purge`. Must be an absolute `https` URL without credentials, or startup fails. While purges are queued, the worker posts JSON `{"patterns": [...], "soft": false}` here every 10 seconds, at most 30 patterns per request, each a media URL prefix without its scheme followed by `*`. Any 2xx marks the patterns done. A `400` or `422` moves the batch to the `cache_purge:rejected` key. Any other failure retries the whole batch on a later run.
+
+#### `FLUXER_CACHE_PURGE_CONTROLLER_TOKEN`
+
+Default empty. Required when the adapter is `controller`. The Controller API key, sent as a bearer token. A token with spaces, line breaks or non-ASCII characters fails startup.
+
+#### `FLUXER_CACHE_PURGE_CONTROLLER_TIMEOUT_MS`
+
+Default `10000`. Timeout of each purge request. Accepts 1000 to 10000. The range is checked only when the adapter is `controller`.
+
 #### `FLUXER_GEOIP_DB_PATH`
 
 Default empty. The GeoIP database. A filesystem path, or an `s3://bucket/key` URL whose `download_path` query parameter is mandatory and must be absolute. Read by `api` and `worker`.