Add a WebSocket stage to one context
This program reads the same Bluesky firehose as bluesky, with websocat
replaced by a native WebSocket stage. It is an example from Hypershell, a
shell-scripting language whose programs are Rust types, built with
Context-Generic Programming (CGP), a Rust library that keeps a context's choices in its
own wiring. The WebSocket stage is an extension that the base language does not include, and this
page shows how one context, the type a program runs on, adds it with two wiring entries, where
http_checksum_native joined an extended namespace.
New to CGP?
This page builds on http_checksum_native, which introduces extending
the language. For CGP itself, the Hello World tutorial is the quickest
start. The page uses CGP's modular error handling, in which
the context chooses the error type, and explains what it needs of it.
The problem
The task is the same firehose, read with a native WebSocket stage instead of the websocat command.
The WebSocket stage is an extension the base language does not include, and it can fail in ways the
base language's error handling does not know about, so the task is to add it, and its errors, to a
single program without changing the language for everyone else.
Without CGP
In a language whose program is an enum interpreted by a match, a new stage is an edit to the
language's crate, and its errors are a new case in the language's error type, so the change reaches
every user. Without a language at all, the WebSocket client is a loop written by hand that reads
messages and writes them to the next command's input. This page adds the stage to one context with
two wiring entries, one for the stage and one for its error, and leaves the language and every other
context unchanged.
Run it
From the root of the Hypershell repository:
cargo run --example bluesky_websocket
It needs the network and grep. It prints firehose events that contain love as they arrive, and
runs until it is stopped with Ctrl-C.
The program
From
bluesky_websocket.rs:
use cgp::core::error::ErrorRaiserComponent;
use cgp_error_anyhow::RaiseAnyhowError;
use hypershell::namespaces::HypershellNamespace;
use hypershell::prelude::*;
use hypershell_tokio_components::types::TokioAsyncReadStream;
use hypershell_tungstenite_components::providers::HypershellTungsteniteProvider;
use tokio::io::simplex;
use tokio_tungstenite::tungstenite::Error as TungsteniteError;
pub type Program = hypershell! {
WebSocket<
StaticArg<"wss://jetstream1.us-west.bsky.network/subscribe">,
(),
>
| StreamingExec<
StaticArg<"grep">,
WithArgs [ FieldArg<"keyword"> ],
>
| StreamToStdout
};
WebSocket connects to the URL and produces the messages it receives as a stream. Its second
parameter is () in this program.
Two entries beside the namespace
The context joins HypershellNamespace and adds two entries of its own:
#[derive(HasField)]
pub struct MyApp {
pub keyword: String,
}
delegate_components! {
MyApp {
namespace HypershellNamespace;
@cgp.core.error.ErrorRaiserComponent.TungsteniteError:
RaiseAnyhowError,
@cgp.extra.handler.HandlerComponent.<Url, Params> WebSocket<Url, Params>:
HypershellTungsteniteProvider,
}
}
The second entry routes the WebSocket syntax to HypershellTungsteniteProvider, the bundle of
providers that the hypershell-tungstenite-components crate publishes. It uses the same full path
the namespace uses for its own routes, starting from @cgp.extra.handler, the prefix under which
CGP's handler component is registered.
The first entry is needed because the WebSocket provider can fail with an error type the base
language has never seen. Every provider reports failure through the context's error type, which
HypershellNamespace sets to anyhow::Error, and it converts each kind of source error through a
route listed for that type. The namespace lists the errors the base language raises, so an extension
that raises a new one must add its route: here tungstenite's error, converted by
RaiseAnyhowError from the cgp-error-anyhow crate, which accepts any type implementing
std::error::Error. The entry names ErrorRaiserComponent in its path, so that component is
imported even though the code never mentions it otherwise.
Entries like these work for syntax the namespace does not already route. A context cannot use the
same form to give SimpleExec a different provider, because the namespace already binds that path;
see the limitations.
An input that stays open
main passes an input that never ends:
let (read, _write) = simplex(102400);
let input = TokioAsyncReadStream::from(read);
app.handle(PhantomData::<Program>, input).await?;
The WebSocket stage forwards its input to the socket and closes the connection when the input ends.
An empty Vec<u8> would therefore end the stream at once. The program instead passes the reading
half of an in-memory pipe whose writing half is kept alive and never written, so the connection
stays open.
Try a change
Remove the error route, keeping the WebSocket entry. The program then fails at its handle call,
and cargo cgp check reports the missing route, shown here with the long
type abridged:
error[E0277]: [CGP-E001] missing wiring for `@cgp.core.error.ErrorRaiserComponent.tokio_tungstenite::tungstenite::Error` on `MyApp`
= note: root cause: [CGP-E113] missing wiring for `@cgp.core.error.ErrorRaiserComponent.tokio_tungstenite::tungstenite::Error` on `MyApp`
The path's last segment is the error type the provider raises, written by its full path:
tokio_tungstenite::tungstenite::Error, the type the program imports as TungsteniteError. So the
message names tungstenite's error rather than the context's own, and adding the route back fixes
it.
cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet
reshape every class.
The pattern
This program shows extending one context rather than the whole language. Entries next to the
namespace statement add syntax for that context alone, with no new type to define. A namespace
that inherits the standard one, as in http_checksum_native, does the
same for every context that joins it. The first suits a single application, and the second an
extension that several applications share.
It also shows how errors work in CGP: code reports its own kinds of error, and the context decides how each one becomes the application's error type. See modular error handling.
The cost is bookkeeping. Every new kind of error an extension can produce needs its own entry, and a context that forgets one finds out from a compile error, which names the missing error type as shown above.
Where to go next
- Examples: every example, in teaching order.
- Writing a program: the steps every example shares, as a guide.
- Error handling in CGP: how a context chooses its error type and how source errors reach it.
- Assembly: context entries and extension namespaces.
- Hypershell: a type-level DSL for shell-scripting in Rust: the post that announced Hypershell, whose last part covers extending the language. Its code predates the current design.
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.