entelechy-protocolGenerated

Layer: interface · Lines of code: 4,893 · Integration test files: 0

Brief

Entelechy creation protocol: JSON lines, over stdin or a WebSocket, that drive a live session

Description

The creation protocol: JSON lines over stdin and stdout.

Any agent drives a live session through the operations the CLI and the Player use. The contract is these operations and the session’s authority rules.

The envelope, and every operation with its fields and answer, are in docs/PROTOCOL.md, Operations, rendered from ops, which the server checks every request against.

Each operation lives in the module for what it may do: inspect reads the session, create changes the scene and its Kernels, run runs them, fields reads and writes a node’s Fields. wire is the JSON shape of values and results; transport carries the lines.


Internal dependencies	`entelechy-compiler`, `entelechy-formats`, `entelechy-graph`, `entelechy-ir`, `entelechy-kernel`, `entelechy-language`, `entelechy-scene`, `entelechy-session`
External dependencies	`serde_json`
Source	`crates/interface/protocol`

Modules

Name	Brief
`envelope`	One request and one answer as they cross a door: a request is one JSON object a line, an answer one line back. What each carries, and the doors a session is reached through, are the table `PARTS` and `DOORS`; `parse_request` reads the one and `envelope` writes the other; `help` answers them.
`help`	Entelechy’s syntax and API, layer by layer, gathered from the tables the implementation executes: the builtins and the forms from the compiler, the reserved words from the parser, what a `domain` may call from the scene’s lowering, what a capability grants from the ABI, a package’s parts from the session, the operations from `crate::ops`, the wire from `crate::envelope`, the replay lines from the replayer. The whole of it as one text, or one name in full.
`ops`	Every operation the protocol answers, as data: what it does, the fields it takes and what it answers. The server checks each request against it, `help` answers from it, and `docs/PROTOCOL.md`’s table is its rendering.
`websocket`	WebSocket framing for the protocol’s socket, so a browser can be a client: the RFC 6455 handshake and text, close, ping and pong frames. The messages carry the same JSON lines as a plain socket.

Structs

Name	Brief
`envelope::Part`	One part of a request, an answer or an error.
`envelope::Door`	A way a session is reached.
`ops::Operation`	One operation.
`ops::Field`	One field of a request.
`websocket::Origins`	The web pages whose scripts a socket answers, judged by `Origin`, so a visited site cannot drive the session. Admitted: a non-browser client (no `Origin`), a page served from this machine (`localhost`, `127.0.0.1`, `[::1]`, any port), and origins named with `--allow-origin`. A page opened from a file says `null`, as does a sandboxed frame on any site, so `null` is admitted only when named.

Enumerations

Name	Brief
`ops::Ty`	The JSON a field holds: what the server checks a request against, what `help` shows and what a schema says.
`websocket::Message`	A message read from the socket.

Functions

Function	Brief
`fn parse_request(line: &str) -> Result<(Value, Value), Value>`	Parses one request line into its echoed id and the request, or an error envelope’s payload.
`fn envelope(id: &Value, response: Result<Value, Value>) -> String`	The response line for a result.
`fn table() -> String`	The envelope as a Markdown table, as the documents render it.
`fn reference() -> String`	The whole of it as one Markdown text: each section, an item a line or two.
`fn named(name: &str) -> Result<Value, Value>`	Every item named `name`, in full: a name may be a builtin, a form, a replay step and an operation at once (`window`, `reset`).
`fn operations() -> Vec<Operation>`	Every operation, in the order an agent meets them.
`fn operation(name: &str) -> Option<Operation>`	The operation named `name`.
`fn names() -> Vec<&'static str>`	Every operation’s name, in order.
`fn check(request: &Value) -> Result<(), Value>`	Refuses a request that carries a field its operation does not take, or lacks one it needs, naming the fields it takes. An unknown operation is left to `crate::handle`.
`fn table() -> String`	The operations as `docs/PROTOCOL.md` shows them: one row each.
`fn handshake(reader: &mut impl BufRead, writer: &mut impl Write, origins: &Origins) -> Result<bool>`	Reads the opening HTTP request. An upgrade from an admitted origin is answered with 101 and returns `true`; an unadmitted origin gets 403 and a non-upgrade 426, both returning `false`.
`fn accept_key(key: &str) -> String`	The `Sec-WebSocket-Accept` value for a client’s key.
`fn read_message(reader: &mut impl Read) -> Result<Option<Message>>`	Reads one message, joining fragments; `Ok(None)` when the peer closed the stream. Pongs are read and dropped.
`fn write_text(writer: &mut impl Write, text: &str) -> Result<()>`	Writes a text message.
`fn write_pong(writer: &mut impl Write, payload: &[u8]) -> Result<()>`	Answers a ping.
`fn write_close(writer: &mut impl Write) -> Result<()>`	Writes a close frame with the normal status.
`fn answer(session: &mut Session, incoming: Incoming) -> bool`	Answers one incoming request; true when the process should end (a `quit` on standard input). A `quit` on a socket closes that connection.
`fn respond_from(session: &mut Session, incoming: &Incoming) -> (String, bool)`	Answers as `respond_line` does, recording changes as from the request’s channel.
`fn respond_line(session: &mut Session, line: &str) -> (String, bool)`	Answers one request line; the flag says whether it asked to quit.
`fn handle(session: &mut Session, request: &Value) -> Result<Value, Value>`	Handles one request by the function for the operation it names.

Constants

Name	Type	Value	Brief
`envelope::PARTS`	`[Part; 22]`	`_`	Every part of the envelope: what a request carries beside its operation’s fields, what an answer carries, and what an error may.
`envelope::DOORS`	`[Door; 3]`	`_`	Every door of a served session; all answer the same operations.
`websocket::MAX_MESSAGE`	`usize`	`_`	The longest request a socket takes, in bytes: a line or a whole WebSocket message. A peer’s announced length is checked against it before anything is held.

Re-exports

Answers, Served, envelope, parse_request, evaluation_json, measure_asked, Incoming, Reply, listen, serve, stdin_into, stdin_lines, CONTEXT_FIELDS, context_given, context_of, report_json, trace_json, type_name, value_from_json, value_json, words_json, words_text

envelope::Part

crates/interface/protocol/src/envelope.rs#L12

One part of a request, an answer or an error.

Properties

Name	Type	Description
`name`	`&'static str`	Its key.
`within`	`&'static str`	Where it stands: `request`, `answer` or `error`.
`ty`	`&'static str`	Its type, as the operations’ fields spell one.
`doc`	`&'static str`	What it says, one sentence.

envelope::Door

crates/interface/protocol/src/envelope.rs#L160

A way a session is reached.

Properties

Name	Type	Description
`name`	`&'static str`	Its name.
`opened`	`&'static str`	How it is opened.
`doc`	`&'static str`	What crosses it, one sentence.

ops::Operation

crates/interface/protocol/src/ops.rs#L12

One operation.

Properties

Name	Type	Description
`name`	`&'static str`	Its name, the request’s `op`.
`summary`	`&'static str`	What it does, in one sentence.
`fields`	`Vec<Field>`	The fields it takes, beside `op` and `id`.
`answer`	`&'static str`	What it answers.

Methods

Function	Description
`fn json(&self) -> Json`	The operation in full, as `help` answers it.

Implemented traits: Clone, Debug

ops::Field

crates/interface/protocol/src/ops.rs#L25

One field of a request.

Properties

Name	Type	Description
`name`	`&'static str`	Its name.
`ty`	`Ty`	The JSON it holds, which the server checks.
`required`	`bool`	Whether a request must carry it.
`doc`	`&'static str`	What it means.

Implemented traits: Clone, Debug

websocket::Origins

crates/interface/protocol/src/websocket.rs#L59

The web pages whose scripts a socket answers, judged by Origin, so a visited site cannot drive the session. Admitted: a non-browser client (no Origin), a page served from this machine (localhost, 127.0.0.1, [::1], any port), and origins named with --allow-origin. A page opened from a file says null, as does a sandboxed frame on any site, so null is admitted only when named.

Methods

Function	Description
`fn with(named: Vec<String>) -> Self`	The local origins and `named`, each as a browser sends it (`https://example.com`, `http://host:8080`).
`fn admits(&self, origin: Option<&str>) -> bool`	Whether a page of `origin` may open the socket.

Implemented traits: Clone, Debug, Default

ops::Ty

crates/interface/protocol/src/ops.rs#L39

The JSON a field holds: what the server checks a request against, what help shows and what a schema says.

Variants

Name	Description
`Str`	A string.
`Int`	A whole number.
`Num`	A number.
`Bool`	true or false.
`Null`	null.
`Value`	Any value: a param’s literal, which the operation reads by the param’s own type.
`Object`	Any object, as an operation answered it: a snapshot.
`Words(&'static [&'static str])`	One of these strings.
`Numbers(&'static [&'static str])`	An array of numbers, one a name: `[x, y]`.
`List(Box<Ty>)`	An array of values of one type.
`Record(Vec<Field>)`	An object of these fields and no others.
`Map(&'static str, Box<Ty>)`	An object whose every key (the name says what one is) holds a value of one type.
`Either(Vec<Ty>)`	One of these.

Methods

Function	Description
`fn describe(&self) -> String`	As `help` and the protocol document show it.
`fn check(&self, value: &Json, at: &str) -> Result<(), String>`	Whether `value` is of this type; else what is wrong, naming where in it by `at`.

Implemented traits: Clone, Debug

websocket::Message

crates/interface/protocol/src/websocket.rs#L43

A message read from the socket.

Variants

Name	Description
`Text(String)`	A text (or binary) message: one request line.
`Ping(Vec<u8>)`	A ping, to answer with a pong carrying the same payload.
`Close`	The peer is closing.

Implemented traits: Debug, Eq, PartialEq, StructuralPartialEq