Racket

Keel: Neutral Contracts for Racket Desktop Runtimes🔗ℹ

package: keel

Keel defines a transport-neutral value codec, structured error shape, schema vocabulary, and lifecycle vocabulary. It deliberately does not define a renderer or protocol frame.

1 Values🔗ℹ

value
app-null : void?

The canonical Null value.

procedure
(app-null? value) → boolean?
value : any/c

Recognizes Null.

procedure
(app-value? value) → boolean?
value : any/c

Recognizes values encodable by v1.

procedure
(encode-app-value value) → bytes?
value : app-value?

Encodes one canonical value.

procedure
(decode-app-value encoded) → app-value?
encoded : bytes?

Decodes exactly one canonical value and rejects trailing bytes.

value
max-encoded-value-size : exact-positive-integer?

The 64 MiB byte budget.

value
max-value-depth : exact-positive-integer?

The maximum container nesting depth.

value
max-value-nodes : exact-positive-integer?

The aggregate value-node budget.

2 Structured errors🔗ℹ

procedure
(app-error? value) → boolean?
value : any/c

Recognizes a transport-neutral structured error.

procedure
(make-app-error code message [data]) → app-error?
  code : app-error-code?
  message : string?
  data : app-value? = app-null

Constructs a transport-neutral error value.

procedure
(app-error-code? value) → boolean?
value : any/c

Recognizes portable kebab-case error tokens.

procedure
(app-error-code error) → string?
error : app-error?

Returns the error code.

procedure
(app-error-message error) → string?
error : app-error?

Returns the human-safe message.

procedure
(app-error-data error) → app-value?
error : app-error?

Returns the structured data value.

3 Schemas🔗ℹ

A schema describes application messages without selecting their transport. Rivet can map a command to an RVT1 RPC while Glaze maps it to a GLZ1 invoke.

struct
(struct scalar-type (name))
name : symbol?

struct
(struct list-type (element))
element : schema-type?

struct
(struct map-type (value))
value : schema-type?

struct
(struct optional-type (element))
element : schema-type?

struct
(struct reference-type (name))
name : string?

value
Null : scalar-type?

value
Bool : scalar-type?

value
Int64 : scalar-type?

value
Float64 : scalar-type?

value
String : scalar-type?

value
Bytes : scalar-type?

value
Value : scalar-type?

value
Error : scalar-type?

value
Unit : scalar-type?

struct
(struct schema-field (name type))
name : string?
type : schema-type?

struct
(struct schema-record (name fields))
name : string?
fields : (listof schema-field?)

struct
(struct schema-enum (name cases))
name : string?
cases : (listof string?)

struct
(struct schema-parameter (name type))
name : string?
type : schema-type?

struct
(struct schema-command (name parameters result error-codes))
  name : string?
  parameters : (listof schema-parameter?)
  result : schema-type?
  error-codes : (listof app-error-code?)

struct
(struct schema-event (name type))
name : string?
type : schema-type?

struct
(struct schema-state (name type))
name : string?
type : schema-type?

procedure
(make-app-schema id
revision
[ #:records records
#:enums enums
#:commands commands
#:events events
#:states states]) → app-schema?
  id : string?
  revision : exact-nonnegative-integer?
  records : list? = null
  enums : list? = null
  commands : list? = null
  events : list? = null
  states : list? = null

Validates references, uniqueness, type placement, and names, then returns a canonical schema.

procedure
(app-schema? value) → boolean?
value : any/c

Recognizes a validated application schema.

procedure
(app-schema-id schema) → string?
schema : app-schema?

Returns the schema identity.

procedure
(app-schema-revision schema) → exact-nonnegative-integer?
schema : app-schema?

Returns the schema revision.

procedure
(app-schema-records schema) → (listof schema-record?)
schema : app-schema?

Returns the records in canonical declaration order.

procedure
(app-schema-enums schema) → (listof schema-enum?)
schema : app-schema?

Returns the enums in canonical declaration order.

procedure
(app-schema-commands schema) → (listof schema-command?)
schema : app-schema?

Returns the commands in canonical declaration order.

procedure
(app-schema-events schema) → (listof schema-event?)
schema : app-schema?

Returns the events in canonical declaration order.

procedure
(app-schema-states schema) → (listof schema-state?)
schema : app-schema?

Returns the states in canonical declaration order.

procedure
(schema-type? value) → boolean?
value : any/c

Recognizes scalar, list, map, optional, and named-reference type descriptors.

procedure
(schema-name? value) → boolean?
value : any/c

Recognizes a non-empty schema identity of at most 255 UTF-8 bytes, excluding control, format, and surrogate code points. Names preserve Racket punctuation and Unicode; consumers map them to collision-checked local identifiers.

procedure
(schema-type->app-value type) → app-value?
type : schema-type?

Returns the normative introspection value for one type descriptor.

procedure
(app-schema->app-value schema) → app-value?
schema : app-schema?

Returns the normative introspection value for schema contract 1.

procedure
(encode-app-schema schema) → bytes?
schema : app-schema?

Canonically encodes the introspection value.

The scalar descriptors are Null, Bool, Int64, Float64, String, Bytes, Value, Error, and Unit. Compound descriptors use list-type, map-type, optional-type, and reference-type. Definitions use schema-field, schema-record, schema-enum, schema-parameter, schema-command, schema-event, and schema-state.

4 Schema compatibility🔗ℹ

Two schema revisions are comparable without a transport. A change is 'breaking when an existing peer can observe a different value, name, type, or closed case set, and 'compatible otherwise. Revision numbers are not interpreted: callers decide whether a revision replaces, supersedes, or accompanies the old one.

struct
(struct schema-change (severity path detail))
  severity : (or/c 'breaking 'compatible)
  path : string?
  detail : string?

One reviewable difference. path is a stable dotted location such as "records.Order.fields.total", and detail explains the rule that fired.

procedure
(app-schema-changes old new) → (listof schema-change?)
old : app-schema?
new : app-schema?

Returns every difference from old to new, sorted by path. Breaking rules include removing a record, field, enum, command, parameter, event, or state; adding a required record field, a command parameter, or a closed enum case; changing any type or command result; adding or removing a declared command error code; and changing the schema identity. Compatible rules include adding a record, enum, command, event, or state, and adding an optional record field.

procedure
(schema-compatible? old new) → boolean?
old : app-schema?
new : app-schema?

Returns #t when app-schema-changes reports no 'breaking change, meaning peers built against old can keep operating against new under the documented wire rules.

5 Lifecycle🔗ℹ

value
lifecycle-states : (listof symbol?)

The lifecycle vocabulary, in order: 'starting, 'ready, 'running, 'stopping, and 'stopped.

value
lifecycle-initial-state : symbol?

The state every shared runtime starts in: 'starting.

procedure
(lifecycle-state? value) → boolean?
value : any/c

Recognizes 'starting, 'ready, 'running, 'stopping, and 'stopped.

procedure
(lifecycle-terminal-state? value) → boolean?
value : any/c

Recognizes the terminal lifecycle state, 'stopped.

procedure
(lifecycle-transition? from to) → boolean?
from : lifecycle-state?
to : lifecycle-state?

Reports whether the transition is part of the shared lifecycle contract.

value
request-terminal-outcomes : (listof symbol?)

The mutually exclusive request outcomes: 'succeeded, 'failed, 'cancelled, and 'timed-out.

procedure
(request-terminal-outcome? value) → boolean?
value : any/c

Recognizes the mutually exclusive request outcomes.

1	Values
2	Structured errors
3	Schemas
4	Schema compatibility
5	Lifecycle