gargamelle/boundary
Receiving, typed output, and paired boundaries bound to authoritative contracts. These optional APIs check JSON before invoking private handlers. Admission, application policy, and operational failures remain separate.
Types
Boundary
opaqueA contract and a private handler invoked only after successful decoding and
semantic checks. Construct with boundary, inspect with boundary_contract,
and submit JSON with forward.
pub opaque type Boundary(a, response)JsonBoundary
opaqueA contract and a private handler receiving verified JSON. Semantic checks
require decoding once; contracts without checks validate without conversion.
Construct with json_boundary, inspect with json_boundary_contract, and
submit admitted JSON with forward_json.
pub opaque type JsonBoundary(a, response)OutputBoundary
opaqueA typed producer path through an existing JSON receiving boundary. Its receiving Contract is authoritative; no second definition is stored.
pub opaque type OutputBoundary(a, response)PairedBoundary
opaqueDecoded loading and typed saving bound to one authoritative full contract. Handler response types are independent; encoding and decoding need not be inverses.
pub opaque type PairedBoundary(a, loaded, saved)Values
pub fn boundary(
contract: gargamelle.Contract(a),
handler: fn(a, gargamelle.Json) -> response,
) -> Boundary(a, response)Bind a handler to its authoritative contract. Construction runs no callbacks.
pub fn boundary_contract(
boundary: Boundary(a, response),
) -> gargamelle.Contract(a)Return the receiving contract without exposing its handler.
pub fn boundary_definition(
boundary: Boundary(a, response),
) -> gargamelle.Plan(a, Nil)Return the receiving contract’s structural definition for schema generation.
pub fn forward(
boundary: Boundary(a, response),
json: gargamelle.Json,
) -> Result(response, gargamelle.ContractError)Decode and check the stored contract once, then invoke the handler once. Rejection invokes no handler. Callback exceptions propagate operationally. A Result response remains nested; output is not checked.
pub fn forward_json(
boundary: JsonBoundary(a, response),
json: gargamelle.Json,
) -> Result(response, gargamelle.ContractError)Verify the stored contract once, then invoke the handler once. Semantic requirements cause one decoding pass; without them no converter runs. Admission and application policy are separate. Certificates from other contracts cannot bypass this check. Exceptions propagate operationally.
pub fn json_boundary(
contract: gargamelle.Contract(a),
handler: fn(gargamelle.VerifiedJson(a)) -> response,
) -> JsonBoundary(a, response)Bind a JSON receiving handler to its authoritative contract.
pub fn json_boundary_contract(
boundary: JsonBoundary(a, response),
) -> gargamelle.Contract(a)Return the receiving contract without exposing its handler.
pub fn json_boundary_definition(
boundary: JsonBoundary(a, response),
) -> gargamelle.Plan(a, Nil)Return the receiving contract’s structural definition for schema generation.
pub fn load(
pair: PairedBoundary(a, loaded, saved),
json: gargamelle.Json,
) -> Result(loaded, gargamelle.ContractError)Decode and check once before invoking the loading handler. Application Results remain nested; rejection skips the handler and operational exceptions propagate.
pub fn output_boundary(
encoder: encoding.Plan(a, Nil),
receiver: JsonBoundary(a, response),
) -> OutputBoundary(a, response)Pair an encoder with an existing receiving boundary. Construction executes no callbacks. The receiver’s Contract is the sole acceptance authority.
pub fn output_contract(
output: OutputBoundary(a, response),
) -> gargamelle.Contract(a)Inspect the exact receiving Contract without exposing its private handler.
pub fn paired_boundary(
contract: gargamelle.Contract(a),
encoder: encoding.Plan(a, Nil),
load_handler: fn(a, gargamelle.Json) -> loaded,
save_handler: fn(gargamelle.VerifiedJson(a)) -> saved,
) -> PairedBoundary(a, loaded, saved)Register decoded ingress and typed egress against one full contract. Construction executes no encoder, converter, requirement, or handler callbacks.
pub fn paired_boundary_contract(
pair: PairedBoundary(a, loaded, saved),
) -> gargamelle.Contract(a)Inspect the exact full contract shared by both directions without callbacks.
pub fn save(
pair: PairedBoundary(a, loaded, saved),
value: a,
) -> Result(saved, encoding.EncodingError)Encode once and check the stored contract once before invoking the saving handler. Semantic requirements inspect reconstructed output, not encoder input. Check-free contracts do not decode. Application Results remain nested; rejection skips the handler and operational exceptions propagate.
pub fn send(
output: OutputBoundary(a, response),
value: a,
) -> Result(response, encoding.EncodingError)Encode once to unverified admitted JSON, then forward through the receiving boundary once. No checked encode is performed before forwarding. Invalid output invokes no handler; accepted output invokes it once. Handler Results remain nested, and callback exceptions remain operational failures.