# marshal-response

## Purpose

This module turns the value returned by a sandboxed handler into a host
`Response`. The sandbox-side handler returns a `SerializedResponse`
(plain object with `status`, ordered header pairs, and base64-url
`bodyBase64`); this module validates that shape with a Zod schema and
constructs the corresponding WHATWG `Response` for the host's request
pipeline to forward to the caller.

The validation step is what stops a misbehaving sandboxed handler
(returning `null`, returning a primitive, returning a partial object
missing `status`) from crashing the host pipeline downstream — and
re-rehydrates the structurally pure JSON shape (`Array<[k, v]>` headers,
`bodyBase64` string) back into the host's class-flavoured `Response`
type.

## Features

- Zod-validated unmarshal — `SerializedResponseSchema` enforces
  `status ∈ [100,599]`, ordered `[name, value]` header pairs, and
  `bodyBase64: string` plus the optional `errorCode`/`errorMessage`
  pair the wire format uses for sandbox-tier exceptions.
- Failure surfacing — non-conformant shapes raise
  `SAND_VM_BRIDGE.UNMARSHAL_FAILED` with the Zod issue list attached
  as `context.issues`.
- Base64-url body decode — `Buffer.from(str, "base64url")` rehydrates
  the bytes; the result feeds straight into `Response`'s
  `BodyInit`-compatible `Uint8Array` slot.
- Headers rehydration — `Array<[name, value]>` is appended onto a fresh
  `Headers` instance so duplicate-name semantics from the sandbox are
  preserved as the response leaves the bridge.
- Bodyless-status enforcement — 204/304 responses drop the body even if
  the sandbox produced one, matching the WHATWG fetch rule the host
  pipeline expects.

## Usage: Basic

```ts
import { unmarshalResponse } from "@suaveplan/api-sandbox-vm-host-bridge/marshal/marshal-response";

const response = unmarshalResponse(await sandboxHandler(serialized));
```

## Usage: Advanced

Use the exported schema to pre-validate cached or replayed responses
before they re-enter the pipeline:

```ts
import { SerializedResponseSchema } from "@suaveplan/api-sandbox-vm-host-bridge/marshal/marshal-response";

const cached = await responseCache.get(key);
const result = SerializedResponseSchema.safeParse(cached);
if (result.success) {
    return cached;
}
return rebuildFromSandbox();
```

## API Reference

- `unmarshalResponse(value: unknown): Response` — synchronous; throws
  `SandboxVmBridgeError(UNMARSHAL_FAILED)` on shape failure.
- `SerializedResponseSchema: z.ZodType<SerializedResponse>` — the Zod
  validator used internally; mirrors the contract published by
  `@suaveplan/api-types/sandbox-bridge`.

## Implementation Notes

Headers cross as a `Headers` instance built via `append()` so duplicates
(multi-`Set-Cookie`, etc.) preserve their iteration order. The body
decode skips the `Buffer.from` call for empty strings so the common
"no body" path costs nothing. Status 204/304 force a `null` body in the
constructed `Response` because WHATWG forbids a body on those codes —
the bridge enforces this so a sandbox that mistakenly attaches one
cannot break the host pipeline.