bookclerk_plugin_sdk::net

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Mediated TCP sockets for native guests (Workers connect() equivalent).

Native plugins must not call socket(AF_INET) / connect themselves. The guest jail denies ambient internet; this module speaks HTTP CONNECT through BOOKCLERK_SOCKET_PROXY, which applies the same bookclerk_plugin_manifest::EgressPolicy as workerd fetch()/connect().

Production native-behind-workerd sets fd:<n> or handle:<n> and multiplexes CONNECT streams over that inherited link (crate::mux). A per-session challenge (SESSION_CHALLENGE_ENV) is written before the first mux frame so a numeric descriptor is not an identity. Pathname, abstract:, and \\.\pipe\ forms remain for tests and older launchers. Native plugins must be rebuilt against this SDK; there is no ambient TCP fallback.

Item Kind Summary
SocketAddress struct Destination for connect.
ConnectOptions struct Options for connect.
PluginSocket struct Bidirectional stream returned by connect.
ProxyStream enum Byte stream to the host CONNECT proxy (past the HTTP handshake).
SecureTransport enum Cloudflare-compatible secureTransport values.
nested_native_jail_requested function True when NESTED_NATIVE_JAIL_ENV is 1.
connect function Open a TCP connection through the Bookclerk socket proxy.
SOCKET_PROXY_ENV constant Env var set by bookclerk-workerd for native-behind-workerd guests.
SOCKET_PROXY_WRITE_ENV constant Windows write half of the inherited socket-proxy mux (handle:<n>).
NESTED_NATIVE_JAIL_ENV constant Optional fail-closed flag: deny ambient TCP when SOCKET_PROXY_ENV is unset.
USER_AGENT_ENV constant The User-Agent the host sends for this guest (bookclerk/<version> (+https://bookclerk.app)).
OWN_USER_AGENT_HOSTS_ENV constant Comma-separated hosts (exact or *. wildcard) where the guest keeps its own User-Agent: the operator-approved [capabilities.network.own_user_agent] hosts. Empty or unset keeps none.
GUEST_IPC_DIR_ENV constant Host-created directory for guest pathname sockets.
SESSION_CHALLENGE_ENV constant Hex-encoded 32-byte secret for the inherited proxy mux.
SESSION_CHALLENGE_LEN constant Length of SESSION_CHALLENGE_ENV before hex encoding.
TEST_EXTRA_ENDPOINT_ENV constant Test-only extra endpoint inherited beside SOCKET_PROXY_ENV.
TEST_EXTRA_ENDPOINT_WRITE_ENV constant Windows write half of TEST_EXTRA_ENDPOINT_ENV (handle:<n>).
TEST_EXTRA_CANDIDATE_ENV constant Test-only identity of the candidate endpoint slot to classify.
TEST_EXTRA_CANDIDATE_WRITE_ENV constant Windows write half of TEST_EXTRA_CANDIDATE_ENV (handle:<n>).
SOCKET_PROXY_ABSTRACT_PREFIX constant Prefix for SOCKET_PROXY_ENV when the proxy is a Linux abstract socket.

Structs

SocketAddress

pub struct SocketAddress {
    pub hostname: String,
    pub port: u16,
}

Destination for connect.

Fields

  • hostname: Hostname or IP literal.
  • port: Destination port.

Implements: Clone, Debug, Eq, PartialEq

ConnectOptions

pub struct ConnectOptions {
    pub secure_transport: SecureTransport,
    pub allow_half_open: bool,
}

Options for connect.

Fields

  • secure_transport: TLS mode.
  • allow_half_open: Accepted for API compatibility; half-close is always allowed.

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

PluginSocket

pub struct PluginSocket {
    /* private fields */
}

Bidirectional stream returned by connect.

PluginSocket::close

pub async fn close(self) -> Result<()>

Close both directions.

Errors

Returns SdkError when shutdown fails.

PluginSocket::stream

pub fn stream(&mut self) -> &mut ProxyStream

Borrow the proxied stream (past CONNECT).

PluginSocket::into_split

pub fn into_split(self) -> Result<(OwnedReadHalf, OwnedWriteHalf)>

Split into owned reader/writer halves (pathname Unix sockets only).

Production native plugins use the mux fd: / handle: link and Self::into_stream. This does not open a TCP socket.

Errors

Returns an unsupported-transport error when the proxy is a multiplexed fd: / handle: link.

PluginSocket::into_stream

pub fn into_stream(self) -> ProxyStream

Consumes the socket, returning the CONNECT-established proxy stream.

PluginSocket::into_unix_stream

pub fn into_unix_stream(self) -> Result<UnixStream>

Consumes the socket, returning the CONNECT-established Unix stream.

Production native plugins use Self::into_stream. This does not open a TCP socket when the proxy is a mux link.

Errors

Returns an unsupported-transport error when the proxy is a multiplexed fd: / handle: link.

PluginSocket::start_tls

pub async fn start_tls(&mut self) -> Result<()>

Start TLS on a starttls socket.

The proxy is byte-transparent, so TLS is end-to-end. Wrap Self::into_stream with tokio-rustls (same pattern as workerd socket.startTls() after secureTransport: "starttls"). Pathname sockets may use Self::into_split. Mux links have no TCP fallback.

Errors

Returns SdkError when secureTransport was not starttls.

Enums

ProxyStream

pub enum ProxyStream {
    Unix(UnixStream),
    Mux(MuxStream),
}

Byte stream to the host CONNECT proxy (past the HTTP handshake).

Variants

  • Unix: Pathname / abstract Unix socket (tests and older launchers).
  • Mux: Inherited fd: / handle: multiplexed link.

Implements: AsyncRead, AsyncWrite

SecureTransport

pub enum SecureTransport {
    Off,
    On,
    StartTls,
}

Cloudflare-compatible secureTransport values.

Variants

  • Off: Plain TCP (default).
  • On: TLS from the first byte. Authors wrap the stream with rustls after CONNECT.
  • StartTls: Plain TCP until PluginSocket::start_tls.

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

Functions

nested_native_jail_requested

pub fn nested_native_jail_requested() -> bool

True when NESTED_NATIVE_JAIL_ENV is 1.

connect

pub async fn connect(
    address: SocketAddress,
    options: ConnectOptions,
) -> Result<PluginSocket>

Open a TCP connection through the Bookclerk socket proxy.

Mirrors import { connect } from "cloudflare:sockets".

Errors

Returns SdkError when the proxy env is missing, CONNECT is denied, or I/O fails.

Constants

SOCKET_PROXY_ENV

pub const SOCKET_PROXY_ENV: &str = "BOOKCLERK_SOCKET_PROXY";

Env var set by bookclerk-workerd for native-behind-workerd guests.

SOCKET_PROXY_WRITE_ENV

pub const SOCKET_PROXY_WRITE_ENV: &str = "BOOKCLERK_SOCKET_PROXY_WRITE";

Windows write half of the inherited socket-proxy mux (handle:<n>).

Unset on Unix and in tests that pass one duplex handle:. Product spawns set it so the guest does not read and write the same named pipe.

NESTED_NATIVE_JAIL_ENV

pub const NESTED_NATIVE_JAIL_ENV: &str = "BOOKCLERK_NESTED_NATIVE_JAIL";

Optional fail-closed flag: deny ambient TCP when SOCKET_PROXY_ENV is unset.

The host no longer sets this (sibling Deny + inherited SOCKET_PROXY is the production contract). SDK HTTP and native TCP still fail closed when this is 1 without a proxy, so tests and older launchers cannot fall through to socket(AF_INET).

USER_AGENT_ENV

pub const USER_AGENT_ENV: &str = "BOOKCLERK_USER_AGENT";

The User-Agent the host sends for this guest (bookclerk/<version> (+https://bookclerk.app)).

Set by the host on native guests. While it is set, crate::http::Client replaces the guest's agent with this value on every request hop, except on hosts listed in OWN_USER_AGENT_HOSTS_ENV. Native guests own their TLS, so this rule lives in the SDK; workerd guests get it from the host's egress bridge instead.

OWN_USER_AGENT_HOSTS_ENV

pub const OWN_USER_AGENT_HOSTS_ENV: &str = "BOOKCLERK_OWN_USER_AGENT_HOSTS";

Comma-separated hosts (exact or *. wildcard) where the guest keeps its own User-Agent: the operator-approved [capabilities.network.own_user_agent] hosts. Empty or unset keeps none.

GUEST_IPC_DIR_ENV

pub const GUEST_IPC_DIR_ENV: &str = "BOOKCLERK_GUEST_IPC_DIR";

Host-created directory for guest pathname sockets.

The native-behind-workerd guest may bind and connect Unix sockets only in this directory (OAuth callback and the macOS Postgres mediator). Linux Postgres still splices through /proc/self/fd. Unset on Windows.

SESSION_CHALLENGE_ENV

pub const SESSION_CHALLENGE_ENV: &str = "BOOKCLERK_SESSION_CHALLENGE";

Hex-encoded 32-byte secret for the inherited proxy mux.

The guest writes these bytes before any mux frame. The host accepts the link only when they match the secret it put in this process's environment. An unrelated child, or another session's guest, does not have this value. A numeric fd: / handle: is not an identity across processes.

SESSION_CHALLENGE_LEN

pub const SESSION_CHALLENGE_LEN: usize = 32;

Length of SESSION_CHALLENGE_ENV before hex encoding.

TEST_EXTRA_ENDPOINT_ENV

pub const TEST_EXTRA_ENDPOINT_ENV: &str = "BOOKCLERK_TEST_EXTRA_ENDPOINT";

Test-only extra endpoint inherited beside SOCKET_PROXY_ENV.

Unix value is fd:<n>. Windows value is handle:<n>, with the write half in TEST_EXTRA_ENDPOINT_WRITE_ENV. The launcher sets these only when it actually transferred the endpoint. Unset is not an observation: the guest classifies the slot named by TEST_EXTRA_CANDIDATE_ENV instead, and reports not-run when that metadata is missing. The guest does not write SESSION_CHALLENGE_ENV to the extra slot: the fixture authenticates the endpoint with its own challenge before the guest opens the mux.

TEST_EXTRA_ENDPOINT_WRITE_ENV

pub const TEST_EXTRA_ENDPOINT_WRITE_ENV: &str = "BOOKCLERK_TEST_EXTRA_ENDPOINT_WRITE";

Windows write half of TEST_EXTRA_ENDPOINT_ENV (handle:<n>).

TEST_EXTRA_CANDIDATE_ENV

pub const TEST_EXTRA_CANDIDATE_ENV: &str = "BOOKCLERK_TEST_EXTRA_CANDIDATE";

Test-only identity of the candidate endpoint slot to classify.

Unix value is fd:<n>. Windows value is handle:<n>, with the write half in TEST_EXTRA_CANDIDATE_WRITE_ENV. This names the slot. It does not grant the launcher permission to transfer the endpoint. Missing metadata is not-run, not proof the endpoint is absent. A live object at the slot that is not the candidate is an identification failure, not absence.

TEST_EXTRA_CANDIDATE_WRITE_ENV

pub const TEST_EXTRA_CANDIDATE_WRITE_ENV: &str = "BOOKCLERK_TEST_EXTRA_CANDIDATE_WRITE";

Windows write half of TEST_EXTRA_CANDIDATE_ENV (handle:<n>).

SOCKET_PROXY_ABSTRACT_PREFIX

pub const SOCKET_PROXY_ABSTRACT_PREFIX: &str = "abstract:";

Prefix for SOCKET_PROXY_ENV when the proxy is a Linux abstract socket.

Generated from crates/bookclerk-plugin-sdk at main · View as Markdown