bookclerk_workerd::socket_proxy

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

Last updated View as Markdown

Host-mediated TCP proxy for native-behind-workerd guests.

Native plugins must not open ambient AF_INET sockets. They speak HTTP CONNECT over an inherited multiplexed link (spawn_link); the launcher applies the same EgressPolicy as workerd fetch()/connect() and splices bytes. spawn_unix remains for unit tests that bind a pathname listener.

Item Kind Summary
LinkPolicy struct The policy one proxy link enforces: the approved egress policy and the rule that applies it to a CONNECT target.
ProxyServer struct In-flight host CONNECT proxy. Dropping it cancels accepts and handlers.
TunnelRule enum Which grants decide whether a tunnel may be dialed.
network_not_granted_response function A 403 network_not_granted refusal for host:port.
spawn_unix function Serve HTTP CONNECT on a Unix listener until the task is cancelled.
spawn_link function Serve HTTP CONNECT on mux-accepted streams from an inherited sibling link.
spawn_link_with_challenge function spawn_link that reads a 32-byte session challenge before any mux frame.
spawn_halves function Serve HTTP CONNECT on mux halves that are already separate pipes.
spawn_halves_with_challenge function spawn_halves that requires challenge on the read half before mux frames.
spawn_link_with_challenge_tag function spawn_link_with_challenge that answers TEST_CHANNEL_IDENT_HOST.
spawn_halves_with_challenge_tag function spawn_halves_with_challenge that answers TEST_CHANNEL_IDENT_HOST.
parse_authority function Parses host:port or [ipv6]:port.
resolved_addresses_denied function True when every resolved address for host is denied by policy.
SOCKET_PROXY_ENV constant Env var naming the socket proxy path for the native SDK.
TEST_CHANNEL_IDENT_HOST constant Reserved CONNECT host answered with the session channel tag.
TEST_CHANNEL_IDENT_PORT constant Port paired with TEST_CHANNEL_IDENT_HOST.

Structs

LinkPolicy

pub struct LinkPolicy {
    pub egress: EgressPolicy,
    pub rule: TunnelRule,
}

The policy one proxy link enforces: the approved egress policy and the rule that applies it to a CONNECT target.

Fields

  • egress: Effective egress policy (manifest narrowed by the operator grant).
  • rule: How a CONNECT target is judged against Self::egress.

LinkPolicy::isolate

pub fn isolate(egress: EgressPolicy) -> Self

Policy for a workerd isolate's egress link.

Arguments
  • egress - Effective egress policy for the plugin.
Returns

A LinkPolicy with TunnelRule::IsolateEgress.

LinkPolicy::admits

pub fn admits(&self, host: &str, port: u16) -> bool

Whether a tunnel to host:port may be dialed under this link's rule.

Arguments
  • host - CONNECT target host.
  • port - CONNECT target port.
Returns

true when the rule admits the target. The resolved addresses are checked separately.

Implements: Clone, Debug, From<EgressPolicy>

ProxyServer

pub struct ProxyServer {
    /* private fields */
}

In-flight host CONNECT proxy. Dropping it cancels accepts and handlers.

The Self::fence flag is the session cancel token. Authority revocation sets that flag directly; handlers race it against parsing, DNS, dial, and the byte relay.

ProxyServer::fence

pub fn fence(&self) -> Arc<AtomicBool>

Cancel flag shared with the session owner.

ProxyServer::cancel

pub fn cancel(&self)

Signal handlers to stop. In-flight work selects on Self::fence.

ProxyServer::unfinished_handlers

pub fn unfinished_handlers(&self) -> usize

Handler tasks that have not finished.

Implements: Drop

Enums

TunnelRule

pub enum TunnelRule {
    TcpGrants,
    IsolateEgress,
}

Which grants decide whether a tunnel may be dialed.

Variants

  • TcpGrants: A native guest's socket: only a TCP grant for host:port (EgressPolicy::allows_tcp).
  • IsolateEgress: A workerd isolate's egress, which carries both fetch() and connect() traffic: the union the isolate may reach (EgressPolicy::allows_isolate_tunnel).

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

network_not_granted_response

pub fn network_not_granted_response(
    egress: &EgressPolicy,
    host: &str,
    port: u16,
    grant: &str,
) -> Vec<u8>

A 403 network_not_granted refusal for host:port.

The body is {"error": {"code", "message", "details"}}; details carries destination and, when a pending network setting names the destination, setting. The x-bookclerk-error header repeats the code so a client can tell this refusal from an upstream 403 without reading the body.

Arguments

  • egress - The policy that refused, for its pending settings.
  • host - The refused host.
  • port - The refused port.
  • grant - The grant the destination is missing from, for the message.

spawn_unix

pub fn spawn_unix(
    listener: UnixListener,
    policy: impl Into<LinkPolicy>,
    fence: Arc<AtomicBool>,
) -> Result<ProxyServer>

Serve HTTP CONNECT on a Unix listener until the task is cancelled.

Errors

Returns an error when the listener cannot be marked non-blocking or converted to a Tokio listener.

pub fn spawn_link<S>(
    link: S,
    policy: EgressPolicy,
    fence: Arc<AtomicBool>,
) -> Result<ProxyServer>
where
    S: AsyncRead + AsyncWrite + Send + Unpin + 'static,

Serve HTTP CONNECT on mux-accepted streams from an inherited sibling link.

Errors

Returns an error only if the accept task cannot be spawned (it does not).

pub fn spawn_link_with_challenge<S>(
    link: S,
    policy: impl Into<LinkPolicy>,
    fence: Arc<AtomicBool>,
    challenge: [u8; 32],
) -> Result<ProxyServer>
where
    S: AsyncRead + AsyncWrite + Send + Unpin + 'static,

spawn_link that reads a 32-byte session challenge before any mux frame.

A mismatch, EOF, or fence closes the link and serves nothing. The numeric descriptor is not treated as the session identity.

Errors

Returns an error only if the accept task cannot be spawned (it does not).

spawn_halves

pub fn spawn_halves<R, W>(
    reader: R,
    writer: W,
    policy: impl Into<LinkPolicy>,
    fence: Arc<AtomicBool>,
) -> Result<ProxyServer>
where
    R: AsyncRead + Send + Unpin + 'static,
    W: AsyncWrite + Send + Unpin + 'static,

Serve HTTP CONNECT on mux halves that are already separate pipes.

Windows product spawns pass two unidirectional handles. Splitting one duplex pipe deadlocks the mux when a read and a write are in flight.

Errors

Returns an error only if the accept task cannot be spawned (it does not).

spawn_halves_with_challenge

pub fn spawn_halves_with_challenge<R, W>(
    reader: R,
    writer: W,
    policy: impl Into<LinkPolicy>,
    fence: Arc<AtomicBool>,
    challenge: [u8; 32],
) -> Result<ProxyServer>
where
    R: AsyncRead + Send + Unpin + 'static,
    W: AsyncWrite + Send + Unpin + 'static,

spawn_halves that requires challenge on the read half before mux frames.

Errors

Returns an error only if the accept task cannot be spawned (it does not).

pub fn spawn_link_with_challenge_tag<S>(
    link: S,
    policy: impl Into<LinkPolicy>,
    fence: Arc<AtomicBool>,
    challenge: [u8; 32],
    channel_tag: &str,
) -> Result<ProxyServer>
where
    S: AsyncRead + AsyncWrite + Send + Unpin + 'static,

spawn_link_with_challenge that answers TEST_CHANNEL_IDENT_HOST.

The tag is not a privilege. CONNECT to that host returns it and does not dial. Every other target still uses policy. Production calls spawn_link_with_challenge, which passes no tag.

Errors

Returns an error when channel_tag is empty, longer than 64 bytes, or contains a byte other than ASCII alphanumeric, -, or _, or when the accept task cannot be spawned.

spawn_halves_with_challenge_tag

pub fn spawn_halves_with_challenge_tag<R, W>(
    reader: R,
    writer: W,
    policy: impl Into<LinkPolicy>,
    fence: Arc<AtomicBool>,
    challenge: [u8; 32],
    channel_tag: &str,
) -> Result<ProxyServer>
where
    R: AsyncRead + Send + Unpin + 'static,
    W: AsyncWrite + Send + Unpin + 'static,

spawn_halves_with_challenge that answers TEST_CHANNEL_IDENT_HOST.

Errors

Returns an error when channel_tag is not a safe token, or when the accept task cannot be spawned. See spawn_link_with_challenge_tag.

parse_authority

pub fn parse_authority(target: &str) -> Result<(String, u16)>

Parses host:port or [ipv6]:port.

Errors

Returns an error when the target is missing a port or the port is not a u16.

resolved_addresses_denied

pub fn resolved_addresses_denied(policy: &EgressPolicy, ips: &[IpAddr]) -> bool

True when every resolved address for host is denied by policy.

Constants

SOCKET_PROXY_ENV

pub const SOCKET_PROXY_ENV: &str = "BOOKCLERK_SOCKET_PROXY";

Env var naming the socket proxy path for the native SDK.

TEST_CHANNEL_IDENT_HOST

pub const TEST_CHANNEL_IDENT_HOST: &str = "bookclerk-test-channel";

Reserved CONNECT host answered with the session channel tag.

Production proxies pass no tag, so this host is an ordinary denied dial. A test sets the tag on the host proxy only. The guest is not given the tag in its environment.

TEST_CHANNEL_IDENT_PORT

pub const TEST_CHANNEL_IDENT_PORT: u16 = 1;

Port paired with TEST_CHANNEL_IDENT_HOST.

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