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
(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
(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 Lifecycle🔗ℹ

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

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

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

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

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

Recognizes the mutually exclusive request outcomes.