Binary attachments and downloads

Some responses that the Oda web app receives carry bytes rather than JSON alone: a file's contents coming down to the page, an image, any result that is binary. Such a response arrives as a multipart response, with one part carrying the JSON envelope and further parts carrying the bytes, which are put back into the result at the places the envelope marks. This page is the reference for that framing: the parts, the rules a valid response obeys, and how a malformed or interrupted response fails. For files going the other way, from the page to Oda, see File uploads in the web app.

How a binary response is framed

• The response becomes multipart. A response that carries bytes arrives as a multipart response (multipart/form-data) instead of a single JSON body. A response with no bytes stays plain JSON, and a failure stays JSON too.
• One part carries the envelope. The part named metadata holds the envelope, the same JSON a response without bytes carries, plus the attachment table: the list of where the bytes belong and which part carries them.
• The other parts carry the bytes. Byte parts are named in sequence under bytes-N, one part for each attached value.

Each entry of the attachment table names three things:

Where the bytes land in the result

• A result-relative path. A path names a place inside the result: a property name in an object, an index in an array, and any nesting of the two.
• The whole result can be the bytes. An empty path means the result itself carries the bytes, as when a call answers with one file's contents.
• No field name is reserved. The attachment table rides beside the result, not inside it, so the framing adds no names of its own: any field that can hold a value can hold bytes.
• A placeholder stands in first. In the JSON the metadata part carries, each attachment's place is marked with null, and the bytes fill those places. A placeholder that already holds a value is refused, so the fill never replaces data that is already there.
• Paths stay apart. No two entries share a path, and no entry's path sits inside another's. An entry that repeats or overlaps another fails the response.

What the page receives

• Bytes come back as bytes. After the parts are read, every place the table named holds a Uint8Array of bytes, backed by an ArrayBuffer. Nothing is turned into text on the way.
• Everything else stays JSON. Values around a byte place cross as they are, and a response without bytes stays plain JSON end to end.
• Compression makes no difference to the bytes. A response that travels gzip-compressed restores the same byte parts.

When a binary response fails

• A malformed response is refused as a whole. A multipart response that breaks the rules above fails the call with an invalid binary response message that names what was wrong. No result from that response is delivered.
• The cases it names: a byte part the table lists that is missing; a part name that appears twice; a part that no entry names; a metadata part that cannot be read as the envelope and its table, or an attachment entry that is not valid; a placeholder that already holds a value; and paths that repeat or sit inside one another.
• A response for another call. Every request carries a call id, and its response must echo the same one. A response that carries a different id fails the call: rpcId mismatch for <endpoint>: sent <id>, got <id>.
• A response cut off part way. A transfer that ends before the response is complete fails the call rather than delivering a short answer. Bytes that keep arriving after the caller has cancelled fail the call too.
• What to do. Ask again; a failed response leaves nothing behind. If the same failure returns, keep the message and the call it names for your DataMind OS administrator.

Questions, answered

Why did a download fail with invalid binary response?

The multipart response was malformed for one of the reasons in When a binary response fails: a missing, repeated or unclaimed part; metadata or an entry that could not be read; an occupied placeholder; or repeated or overlapping paths. No result was delivered. Ask again, and keep the message for your administrator if it returns.

What is a result-relative path?

The route to a place inside the result: property names, array indices, and any nesting of the two. An empty path means the whole result is the bytes. The attachment table rides beside the result, so no field name is reserved; a path simply points at where the bytes sit.

Why must a placeholder be null?

The bytes are put into the result at the places the table names, and each of those places must be marked with null first. A place that already holds a value is refused instead of overwritten, so the bytes never quietly replace data that was already there.

Can one response carry several values of bytes?

Yes. Each attachment gets its own entry and its own part, named in sequence under bytes-N. The paths must stay unique and must not overlap, so every part lands in its own place.

Do the bytes arrive as text?

No. Every byte place ends up holding a Uint8Array of raw bytes, backed by an ArrayBuffer. Nothing is turned into text on the way, and the JSON values around the bytes are unchanged.

Why did a call fail with rpcId mismatch?

The response carried a different call id than the request sent, so it was not delivered. Every request carries a call id, and its response must echo the same one. Ask again; if the message returns, keep it for your administrator.

What happens if the response is cut off part way?

The call fails, and no short answer is delivered: the response must arrive whole. Bytes that keep arriving after the caller has cancelled fail the call in the same way.

Does compression make a difference to the bytes?

No. The same byte parts are restored whether or not a response is compressed; gzip does not alter the bytes.

Where in the result can bytes sit?

Anywhere a value can: a top-level field, a field nested in others, an item of an array, or the whole result under an empty path. The framing reserves no field names, so the result keeps its own shape.

What does the codec field say?

Each entry declares how its bytes are coded, and the codec for these attachments is bytes: the part carries the raw bytes themselves. An entry that does not declare a valid codec makes the response invalid.