Design

Where ruststream-sea-file sits: between the RustStream runtime and the two sea-streamer clients, a column for the stream file and one for the pipe.

The diagram as text

1. Your service: #[subscriber] handlers; RustStream::new(..) .with_broker(..)
2. RustStream core: Runtime: dispatch, codec, settlement, retries
3. ruststream-sea-file: FileSubscriber driver task; StdioSubscriber reader task; FilePublisher; StdioPublisher; FileBroker ConnectedFileBroker; StdioBroker ConnectedStdioBroker; Header envelope headers inside the payload
4. sea-streamer clients: sea-streamer-file; sea-streamer-stdio
5. #[subscriber] handlers → Runtime: dispatch, codec, settlement, retries: mounted
6. Runtime: dispatch, codec, settlement, retries → FileSubscriber driver task: polls the stream
7. Runtime: dispatch, codec, settlement, retries → StdioSubscriber reader task
8. FileSubscriber driver task → sea-streamer-file
9. StdioSubscriber reader task → sea-streamer-stdio
10. sea-streamer-file → A .ss file on disk
11. sea-streamer-stdio → stdin and stdout
12. Under testing, a broker's link can be a file or a pipe held in memory instead of the client

The crate implements the core's broker traits over two clients of sea-streamer: sea-streamer-file for a stream file and sea-streamer-stdio for the process's standard input and output. The runtime above it is the same for every broker. What is specific to a file or a pipe is in this crate: the descriptor, positions and seeking, what an ack means, where a retry copy goes and how headers travel.

A connected broker holds one link to its transport. For a file it is the client's streamer, one producer that every publish appends through, and the runtime connect ran on. For stdio it is the client's streamer and that runtime. Every clone of a broker shares the link, so connecting twice connects once, and a publisher handed out before connect finds it on its first publish.

Every task of a connection runs on the runtime connect ran on. A subscription opened from another runtime therefore keeps delivering after that runtime stops.

A file subscription is a driver task that owns the client's consumer, because the client's seek needs the consumer to itself and cannot be interrupted. A stdio subscription is a reader task. Both hand their messages over a channel of 64, and both clients read one message at a time, so a batch is assembled in the crate. A partial batch leaves 10 milliseconds after its first message.

Neither transport takes per-message settings, so a publish has no options. The clients take a payload and no headers, so headers travel inside the payload, in the envelope.

How the pieces start and stop is on Lifecycle, and the way of one message on Path.