Wire Contracts

Status: DRAFT v0.1

Everything in this document crosses a process boundary. These are the contracts that make two Benzene implementations — in any two languages, on any two vendors — interoperable. From spec 1.0, changes here are breaking changes.

All JSON field names below are camelCase unless stated otherwise. All header keys are case-insensitive on read and SHOULD be written lower-case.

1. The Benzene message envelope

The transport-neutral message format, used whenever a Benzene client sends to a Benzene service over a transport with no richer native contract (direct function invocation, queues without attribute support, the generic BenzeneMessage entry point).

1.1 Request

{
  "topic": "order:create",
  "headers": { "x-correlation-id": "…", "traceparent": "…" },
  "body": "{ …serialized message… }"
}

(Informative: earlier .NET versions had the outbound Lambda client sending this field as message while the inbound entry point read body — corrected to body on both sides; body is normative.)

1.2 Response

{
  "statusCode": "Ok",
  "headers": { },
  "body": "{ …serialized response… }"
}

1.3 Error payload

When a result is unsuccessful, the response body is the serialized error payload — a problem-details-shaped object:

{
  "status": "NotFound",
  "detail": "No handler found for topic order:create"
}

Clients recover errors from detail; a missing/empty detail yields an error-free failed result.

2. Header conventions

Headers are the portable metadata channel. Every transport binding maps its native metadata (HTTP headers, gRPC metadata, SQS/SNS message attributes, Kafka headers, the envelope's headers field) to and from this flat string→string dictionary.

Binary metadata (e.g. gRPC -bin keys) is excluded from the dictionary in both directions. Duplicate keys: last value wins.

3. Status vocabulary

The closed set of framework-defined statuses. The strings below are the wire values — they are PascalCase and case-sensitive.

Applications MAY use additional status strings; every mapping table below routes unknown statuses to its generic-error row.

4. Per-protocol status mappings

4.1 HTTP

Reverse (HTTP → Benzene, used by HTTP clients): 200→Ok, 201→Created, 202→Accepted, 204→Deleted, 400→BadRequest, 401→Unauthorized, 403→Forbidden, 404→NotFound, 408→Timeout, 409→Conflict, 422→ValidationError, 429→TooManyRequests, 501→NotImplemented, 502→ServiceUnavailable, 503→ServiceUnavailable, 504→Timeout, anything else→UnexpectedError.

4.2 gRPC

Forward (server):

The benzene-status trailer: because several Benzene statuses collapse to one gRPC code, a Benzene gRPC server MUST attach a response trailer benzene-status carrying the raw status string verbatim, on success and failure alike. A missing result maps the trailer value to Unknown. Non-OK outcomes are surfaced as a gRPC error with the mapped code and a detail string of the joined errors (or the raw status if errors is empty).

Reverse (client): a benzene-status trailer, when present, wins verbatim. Otherwise: OK→Ok, InvalidArgument→BadRequest, Unauthenticated→Unauthorized, PermissionDenied→Forbidden, NotFound→NotFound, AlreadyExists→Conflict, Unimplemented→NotImplemented, Unavailable/Cancelled→ServiceUnavailable, ResourceExhausted→TooManyRequests, DeadlineExceeded→Timeout, anything else→UnexpectedError.

Cancellation: a cancelled invocation maps to gRPC DeadlineExceeded if the call's deadline has passed, else Cancelled.

5. Health check response

Returned for the reserved topic healthcheck (and any app-configured alias):

{
  "isHealthy": true,
  "healthChecks": {
    "Database": {
      "status": "ok",
      "type": "Database",
      "data": { "CanConnect": true }
    }
  }
}

• status per check is one of "ok", "warning", "failed" (lower-case — note this is a different vocabulary from §3).
• isHealthy is true iff no check reports "failed"; "warning" does not flip it.
• healthChecks keys are check names, deduplicated with -2/-3 suffixes on collision.
• data is a free-form diagnostic bag; its keys are written verbatim (no naming policy applied).

gRPC hosts additionally expose the same aggregate over standard grpc.health.v1: SERVING iff no check failed (a warning maps to a degraded-but-serving state).

6. Serialization defaults

• Default payload encoding is JSON, UTF-8.
• Writing: camelCase property names. Writers MAY omit null-valued properties or emit them as null; readers MUST accept both.
• Reading: property-name matching is case-insensitive.
• gRPC payload bridging uses protobuf's own JSON mapping (proto3 JSON) between protobuf messages and plain types — not a naive reflection round-trip — so enums, well-known types, and oneofs convert per protobuf rules. Property matching is against the protobuf JSON names.