Crate netbat

Expand description

Lean, sync-first server/network boundary exposure layer (blocking transport, TLS opt-in).

netbat is a lean, blocking transport boundary: nb exposes, sb dispatches, bp records. It stays narrow in remit — synchronous and blocking per connection, with a small default dependency graph (TLS is opt-in). This crate can describe server-facing modules, endpoints, and route tables around syncbat modules or cores. It can also handle bounded sync transport frames, but it does not own dispatch decisions, run handlers directly, or write batpak records.

The crate is designed to be imported as:

use netbat as nb;

§Frame round-trip

Encode a CALL request, decode it back, and inspect the parts. The encoder enforces the operation-name grammar via the substrate OperationName newtype; downstream code never re-parses.

use netbat as nb;

let frame = nb::encode_request("system.heartbeat", &[0xde, 0xad]);
assert_eq!(frame, b"NETBAT/1 CALL system.heartbeat dead\n");

let parsed = nb::decode_line(&frame, &nb::Limits::default()).expect("decode");
assert_eq!(parsed.operation(), "system.heartbeat");
assert_eq!(parsed.input(), &[0xde, 0xad]);

§Response framing

encode_response emits either OK <hex>\n or ERR <code> <hex>\n. The ERR-frame code is a stable token from NetbatError::code — never a runtime string. The message half is hex of UTF-8 text, not MessagePack.

use netbat as nb;

// Success: OK <hex>\n
let ok = nb::encode_response(Ok(b"hi"));
assert_eq!(ok, b"OK 6869\n");

// Error: ERR <code> <hex>\n
let err = nb::NetbatError::MalformedRequest { reason: "bad" };
let err_frame = nb::encode_response(Err(&err));
assert!(err_frame.starts_with(b"ERR malformed_request "));
assert!(err_frame.ends_with(b"\n"));

§Connection limits and dispatch

A blocking listener caps the connections it serves through ConnectionLimit (the connection_limit field on TcpServerConfig and TcpSubscriptionServerConfig). The default, ConnectionLimit::Concurrent, is an in-flight permit pool sized at DEFAULT_MAX_CONNECTIONS: at most n connections are served at once and a freed slot is immediately reusable. It REPLACES the pre-0.9 max_connections lifetime accept budget, which is now the explicit opt-in ConnectionLimit::Lifetime; ConnectionLimit::Unlimited removes the gate entirely.

The subscription listener additionally chooses how each accepted session is served via SubscriptionDispatch. The default, SubscriptionDispatch::Concurrent, spawns a contained worker per session so subscribers stream concurrently (gated by the same permit pool); SubscriptionDispatch::Sequential keeps the pre-0.9 inline behavior where one long-lived subscriber blocks the accept loop until its session ends.

use netbat as nb;

// Both listeners default to a concurrent in-flight permit pool, and
// subscriptions are served concurrently.
assert!(matches!(
    nb::ConnectionLimit::default(),
    nb::ConnectionLimit::Concurrent(_),
));
assert_eq!(nb::SubscriptionDispatch::default(), nb::SubscriptionDispatch::Concurrent);

// Opt into the pre-0.9 lifetime accept budget — or remove the gate entirely.
let config = nb::TcpServerConfig::default()
    .with_connection_limit(nb::ConnectionLimit::Unlimited);
assert_eq!(config.connection_limit, nb::ConnectionLimit::Unlimited);

§Security / transport trust model

netbat has no authentication and no authorization, by design. Identity and access control are downstream-domain concerns: authenticate and authorize at a fronting proxy or in the application layer that owns the syncbat runtime, never inside netbat. netbat only frames bytes, maps stable error codes, and moves bounded request/response and subscription frames over a blocking transport.

Without the tls feature (the default) netbat speaks plaintext and so assumes a trusted transport: bind it to loopback, a private network segment, or behind a TLS-terminating reverse proxy. There is no in-process confidentiality on the plaintext path.

Enabling the opt-in tls feature adds server-only TLS (rustls): it provides confidentiality and server identity only — it does not authenticate the client (auth still lives above netbat). Build a TlsServerConfig from PEM and pass TransportSecurity::Tls to serve_tcp_listener_secured (or serve_tcp_subscription_listener_secured). The rustls handshake runs on the per-connection worker after the concurrency permit is acquired, so a slow or hostile handshake occupies at most one worker+permit slot and never blocks the accept loop; a failed handshake (for example, a cleartext peer) is counted in TcpServeStats::tls_handshake_failures and the connection is dropped — never listener-fatal. See TlsServerConfig for a PEM example.

Structs§

ClientWindow: Client-side receive window (nonzero).
CoreHealth: Borrowed health check over a syncbat core’s mounted operation descriptors.
CursorBytes: Opaque cursor bytes carried on the wire as lowercase hex.
DeliveryIndex: Monotonic per-subscription delivery index (nonzero).
Endpoint: A syncbat operation exposed at a server/network boundary.
Introspection: Introspection report for exposed boundary metadata.
IoTimeouts: Optional read/write timeout hints for listener owners.
Limits: Bounded transport limits for netbat’s blocking line protocol.
OperationName: Stable operation name. Validated once at construction; downstream code never re-parses the grammar.
PayloadSchemaRef: Opaque payload schema ref token (interpreted above netbat).
RequestFrame: Decoded request frame for netbat’s blocking line protocol.
ResponseFrame: Encoded runtime output returned through a netbat transport frame.
Route: A mounted boundary route.
Server: Minimal server-boundary registry.
ServerModule: Server-facing wrapper for a data-oriented syncbat module.
ShutdownHandle: Shared shutdown flag for blocking TCP listener loops.
StreamReasonCode: Stable lowercase stream reason/code token.
SubAckFrame: NETBAT/2 SUB_ACK frame.
SubCancelFrame: NETBAT/2 SUB_CANCEL frame.
SubEndFrame: NETBAT/2 SUB_END frame.
SubErrFrame: NETBAT/2 SUB_ERR frame.
SubEventFrame: NETBAT/2 SUB_EVENT frame.
SubWatermarkFrame: NETBAT/2 SUB_WATERMARK frame.
SubscribeFrame: NETBAT/2 SUBSCRIBE frame.
SubscriptionToken: Globally unique subscription id (orders.open.v1 grammar).
TcpServeStats: Summary returned after a blocking TCP listener exits.
TcpServerConfig: Blocking TCP server limits.
TcpSubscriptionServeStats: Summary returned after a NETBAT/2 subscription listener exits.
TcpSubscriptionServerConfig: Blocking NETBAT/2 subscription listener configuration.

Enums§

ConnectionLimit: How a listener caps the connections it serves.
MaybeCursor: Optional cursor field encoded as - when absent.
NetbatError: Error returned by netbat transport framing or syncbat dispatch.
OperationNameError: Operation-name grammar violation surfaced by OperationName::new.
RouteValidationError: Boundary route validation failure.
StreamFrame: Decoded NETBAT/2 streaming frame.
SubscriptionDispatch: How the subscription listener dispatches each accepted session.
TransportSecurity: Transport security applied to a request listener’s accepted connections.

Constants§

CALL_VERB: Request verb used by netbat’s line protocol.
DEFAULT_MAX_CONNECTIONS: Default concurrent connection cap. Matches the pre-0.9 max_connections magnitude so a default listener admits the same volume, now as an in-flight concurrency cap rather than a lifetime accept budget.
DEFAULT_MAX_CURSOR_BYTES: Default maximum opaque cursor bytes decoded from stream frames.
DEFAULT_MAX_INPUT_BYTES: Default maximum decoded input size accepted by the line transport.
DEFAULT_MAX_LINE_BYTES: Default maximum request line size accepted by the line transport.
DEFAULT_MAX_OPERATION_NAME_BYTES: Default maximum operation name size accepted by the line transport.
DEFAULT_MAX_OUTPUT_BYTES: Default maximum handler output size encoded into a response frame.
DEFAULT_MAX_REQUESTS_PER_CONNECTION: Default maximum requests served from one accepted TCP connection.
DEFAULT_MAX_STREAM_ERROR_MESSAGE_BYTES: Default maximum decoded SUB_ERR message bytes.
DEFAULT_MAX_STREAM_PAYLOAD_BYTES: Default maximum decoded subscription event payload bytes.
DEFAULT_MAX_SUBSCRIPTION_ID_BYTES: Default maximum subscription id bytes accepted by NETBAT/2 stream frames.
LAYER_RULE: Stable crate-layer rule for docs, diagnostics, and tests.
LINE_PROTOCOL_VERSION: Current version token accepted by netbat’s versioned line protocol.
MAX_ROUTE_PATH_BYTES: Maximum bytes accepted for a boundary route path.
PROTOCOL_PREFIX: Prefix used by every versioned netbat line-protocol token.
STREAM_PROTOCOL_VERSION: Current version token accepted by NETBAT/2 subscription streaming frames.
SUBSCRIBE_VERB: Open/resume verb for NETBAT/2 streaming frames.
SUB_ACK_VERB: Cumulative ack verb for NETBAT/2 streaming frames.
SUB_CANCEL_VERB: Cancel verb for NETBAT/2 streaming frames.
SUB_END_VERB: End verb for NETBAT/2 streaming frames.
SUB_ERR_VERB: Error verb for NETBAT/2 streaming frames.
SUB_EVENT_VERB: Delivery verb for NETBAT/2 streaming frames.
SUB_WATERMARK_VERB: Watermark verb for NETBAT/2 streaming frames.

Functions§

decode_hex: Decode a lowercase or uppercase hexadecimal byte string with a decoded-size limit.
decode_hex_str: Decode a lowercase or uppercase hexadecimal &str.
decode_line: Decode one netbat line-protocol request.
decode_stream_line: Decode one NETBAT/2 streaming line frame.
dispatch_frame: Dispatch a decoded request frame through syncbat.
encode_hex: Encode bytes as a lowercase hexadecimal byte string and return the owned buffer.
encode_hex_into: Append lowercase hexadecimal encoding of bytes into output.
encode_hex_str: Encode bytes as a lowercase hexadecimal String.
encode_request: Encode a stable versioned request line.
encode_response: Encode a stable response line.
encode_stream_frame: Encode one NETBAT/2 streaming frame as a newline-terminated line.
inspect_core_operations: Inspect whether named operations are mounted in a borrowed syncbat core.
introspect_modules: Build an introspection report over server-facing module metadata.
serve_stream: Serve one request from an already-accepted blocking stream.
serve_subscription_stream: Serve one NETBAT/2 subscription stream over split reader/writer handles.
serve_tcp_listener: Serve a blocking TCP listener until shutdown or limits stop it.
serve_tcp_listener_secured: Serve a blocking TCP listener with a chosen TransportSecurity.
serve_tcp_subscription_listener: Serve a blocking NETBAT/2 subscription TCP listener.
serve_tcp_subscription_listener_secured: Serve a NETBAT/2 subscription listener with a chosen TransportSecurity.

Crate netbat

Crate netbat Copy item path

§Frame round-trip

§Response framing

§Connection limits and dispatch

§Security / transport trust model

Structs§

Enums§

Constants§

Functions§

Crate netbat