bookclerk_plugin_sdk::net
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. |
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
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
pub struct PluginSocket {
/* private fields */
}
Bidirectional stream returned by connect.
pub async fn close(self) -> Result<()>
Close both directions.
Returns SdkError when shutdown fails.
pub fn stream(&mut self) -> &mut ProxyStream
Borrow the proxied stream (past CONNECT).
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.
Returns an unsupported-transport error when the proxy is a multiplexed
fd: / handle: link.
pub fn into_stream(self) -> ProxyStream
Consumes the socket, returning the CONNECT-established proxy 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.
Returns an unsupported-transport error when the proxy is a multiplexed
fd: / handle: link.
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.
Returns SdkError when secureTransport was not starttls.
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: Inheritedfd:/handle:multiplexed link.
Implements: AsyncRead, AsyncWrite
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 untilPluginSocket::start_tls.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub fn nested_native_jail_requested() -> bool
True when NESTED_NATIVE_JAIL_ENV is 1.
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".
Returns SdkError when the proxy env is missing, CONNECT is denied, or
I/O fails.
pub const SOCKET_PROXY_ENV: &str = "BOOKCLERK_SOCKET_PROXY";
Env var set by bookclerk-workerd for native-behind-workerd guests.
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.
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).
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.
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.
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.
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.
pub const SESSION_CHALLENGE_LEN: usize = 32;
Length of SESSION_CHALLENGE_ENV before hex encoding.
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.
pub const TEST_EXTRA_ENDPOINT_WRITE_ENV: &str = "BOOKCLERK_TEST_EXTRA_ENDPOINT_WRITE";
Windows write half of TEST_EXTRA_ENDPOINT_ENV (handle:<n>).
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.
pub const TEST_EXTRA_CANDIDATE_WRITE_ENV: &str = "BOOKCLERK_TEST_EXTRA_CANDIDATE_WRITE";
Windows write half of TEST_EXTRA_CANDIDATE_ENV (handle:<n>).
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