bookclerk_workerd::socket_proxy
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. |
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 aCONNECTtarget is judged againstSelf::egress.
pub fn isolate(egress: EgressPolicy) -> Self
Policy for a workerd isolate's egress link.
egress- Effective egress policy for the plugin.
A LinkPolicy with TunnelRule::IsolateEgress.
pub fn admits(&self, host: &str, port: u16) -> bool
Whether a tunnel to host:port may be dialed under this link's rule.
host-CONNECTtarget host.port-CONNECTtarget port.
true when the rule admits the target. The resolved addresses are
checked separately.
Implements: Clone, Debug, From<EgressPolicy>
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.
pub fn fence(&self) -> Arc<AtomicBool>
Cancel flag shared with the session owner.
pub fn cancel(&self)
Signal handlers to stop. In-flight work selects on Self::fence.
pub fn unfinished_handlers(&self) -> usize
Handler tasks that have not finished.
Implements: Drop
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 forhost:port(EgressPolicy::allows_tcp).IsolateEgress: A workerd isolate's egress, which carries bothfetch()andconnect()traffic: the union the isolate may reach (EgressPolicy::allows_isolate_tunnel).
Implements: Clone, Copy, Debug, Eq, PartialEq
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.
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.
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.
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.
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.
Returns an error only if the accept task cannot be spawned (it does not).
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.
Returns an error only if the accept task cannot be spawned (it does not).
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.
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.
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.
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.
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.
pub fn parse_authority(target: &str) -> Result<(String, u16)>
Parses host:port or [ipv6]:port.
Returns an error when the target is missing a port or the port is not a
u16.
pub fn resolved_addresses_denied(policy: &EgressPolicy, ips: &[IpAddr]) -> bool
True when every resolved address for host is denied by policy.
pub const SOCKET_PROXY_ENV: &str = "BOOKCLERK_SOCKET_PROXY";
Env var naming the socket proxy path for the native SDK.
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.
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