Output Image HTTP

How it fits

Typical backends

Caveats

• I/O contractThe first input accepts an Image or one record containing image: Image and metadata: [(String, String)]. A record carries image bytes and identity together. Its metadata pairs use their own keys; keys must be unique across the record and any additional metadata inputs. Each input event produces one encoded image at the input rate whenever a reader or HTTP destination exists.
• I/O contractWhen transports includes websocket or mjpeg the server listens on port 9001: WebSocket subscribers connect on ``/ws`` or ``/``, the MJPEG stream is ``GET /`` or ``GET /mjpeg``, and ``GET /health`` answers ok; without the mjpeg mode a plain ``GET /`` returns 426 and any other path 404. With only http selected no listener starts.
• I/O contractAn mjpeg entry in transports serves a persistent multipart/x-mixed-replace response per client and does not POST to url; set image_format to jpg for canonical Motion JPEG.
• Hard constrainttransports is fixed at startup and accepts only the http, websocket, and mjpeg modes (run together); image_format accepts only png or jpg, with JPEG always dropping alpha and PNG keeping it when preserve_alpha is set.
• I/O contractmetadata_keys names the optional variadic inputs that follow the image; an unnamed extra input is exposed under an index-based name and shipped under metadata_json_header on the HTTP request or in the paired WebSocket frame.
• I/O contractThe WebSocket metadata text frame that precedes each binary image frame is best-effort: the frames of one image go to each subscriber in order and the first one dropped by backpressure ends that subscriber's frames for the image, so a dropped metadata frame also costs that subscriber the binary frame, and a dropped binary frame leaves its metadata frame without the image. Drops are counted, not logged. Scalar string metadata shipped as per-item HTTP header lines that contains a CR, LF or NUL byte raises, naming its metadata key, and stops the worker; the same value in a WebSocket metadata frame is carried unchanged as JSON.
• CostA frame with no audience is not encoded at all: without an http entry in transports, zero WebSocket subscribers and zero MJPEG clients mean the input is consumed and skipped. With an http entry every frame is encoded.
• Hard constraintOnly BGR, RGB, GRAY, BGRA and RGBA images are accepted; any other format raises and stops the worker on every image, whether or not anything reads it; an encode failure raises when the image is encoded, as does a full queue under fail_on_error.
• State lifetimeA changed url applies only to images accepted after the change; images already queued or retrying keep the URL they were accepted with.
• LimitationMemory holds up to queue_capacity plus max_in_flight encoded images at once, plus the one just encoded; queue_capacity accepts at most 4096. The listener on port 9001, present with websocket or mjpeg, takes payloads up to 32 MiB and bounds the backlog queued for one connection at 64 MiB.
• Parameter interactionA set allow_origin is written as Access-Control-Allow-Origin and answers a preflight, which is what a page on another origin needs to read the MJPEG stream through fetch or draw it onto a canvas; every WebSocket connection is pinged every websocket_keepalive_seconds seconds (Nothing sends no pings) and the listener never closes one for being idle.
• I/O contractcontent_type is both the HTTP Content-Type and the media type of each MJPEG part; Nothing picks image/png or image/jpeg from image_format. include_metadata_headers gates every metadata header line, the aggregate JSON one and the per-item ones.
• FallbackHTTP delivery is asynchronous with bounded exponential-backoff retries; when the queue fills, fail_on_error decides whether the oldest request is dropped or the call fails, unless wait_when_full is set, which holds the next tick until a request has been sent.
• Hard constraintAn http entry in transports needs url. url may start unset and be set after deploy, but each image that arrives while it is unset raises and stops the worker, whatever other transports are selected.
• Parameter interactionmax_in_flight requests are sent at once, so a destination answering in 60 ms takes about 16 images a second at one and eight times that at eight. At one under wait_when_full they arrive in order (without it a failed one is retried behind those queued after it); above one they arrive in the order their requests finish and a failed one is retried while later ones go out, so raise it only when the destination does not rely on arrival order, for example one that places images by a per-image timestamp the worker does not read. Under wait_when_full the requests in flight count against queue_capacity.
• State lifetimeOnly url can be changed at runtime; all other keys are captured once at startup.
• FallbackA request to url is retried on any response other than 2xx, 4xx included, and on a transport error or a timeout. Once max_retries retries have failed the image is logged with its last failure and dropped, so a destination that keeps refusing an image never receives it. Images still queued when the worker stops are logged and dropped.
• Hard constraintStartup aborts when max_retry_delay_ms is below initial_retry_delay_ms; password is sent only with a set username. The types hold timeout_seconds at one second or more and both retry delays at one hour or less.
• LimitationThe listener on port 9001, present with websocket or mjpeg, checks no credentials: whoever can reach the port, or holds the deployment's forward link to it, reads every image on the WebSocket and the MJPEG stream.