# controller\_media\_runner\_callback

Source: https://zotonic.com/docs/2707/controller_media_runner_callback

URI: https://zotonic.com/id/2707

Language: en



Client-side receiver for results produced by the external [media runner](https://github.com/zotonic/mediarunner) site. This controller belongs to `mod_base`, so each client site has a callback endpoint without installing the runner site itself.

Endpoint
--------

The `media_runner_callback` dispatch accepts `POST /media-runner/callback?id=<job-id>` with `Content-Type: application/json` and `Authorization: Bearer <secret>`. The body must be a JSON object containing the runner's result envelope. Its size is bounded by `z_media_runner_protocol:callback_limit/0` before JSON decoding.

Place in the processing flow
----------------------------

1. A client calls `z_exec:run/4` with its site context. When remote processing is configured, `z_media_runner` registers the waiting process, creates a job ID and random callback secret, and builds an absolute URL using the client's `media_runner_callback` dispatch rule.
2. The client submits the job to the runner using OAuth2. The job includes that callback URL and secret. The runner queues the command, executes it in the sandbox, and POSTs its JSON result here with `?id=<job-id>` and the secret in the `Authorization: Bearer <secret>` header.
3. This controller authenticates the callback and forwards the decoded result to `z_media_runner`. The waiting client process then uses `z_media_runner_protocol:unpack/2` to validate the result and restore output files to the paths declared by the original caller. This controller does not execute commands or write the returned media files.

Callback authentication
-----------------------

The dispatch rule is anonymous deliberately: this endpoint authenticates with the per-job callback secret, not the OAuth2 token used to submit jobs to the runner, nor a browser session. `z_media_runner` keeps only the secret's hash and associates it with the waiting process. Both the job ID and secret must match.

The request query is already parsed before `is_authorized/1`. Reading the job ID there lets us reject unauthorized requests before allocating the bounded result body. Responses have cache prevention headers; media payloads and callback secrets are not logged.

Delivery and lifetime
---------------------

HTTP 204 acknowledges delivery to the waiting process, including a result that reports a processing failure. It does not mean that output validation succeeded. Malformed JSON or a non-map result returns 400; missing or malformed credentials return 401. Unknown jobs and non-matching secrets return 410. The runner treats 410 as final and stops retrying that callback.

While the job is registered, duplicate authenticated callbacks are acknowledged without notifying the waiting process again. The registration is removed when the call finishes, times out, or its process dies. Late callbacks then return 410. Registrations are in memory on the submitting Zotonic node; cluster routing must send callbacks back to that node, and a node restart loses pending registrations.

See the [media runner documentation](https://github.com/zotonic/mediarunner#readme) for deployment and client configuration.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2707?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2707?language=en>)
