bookclerk_workerd::egress_relay
The launcher's egress relay: a workerd isolate's only way out of its jail.
Every workerd jail is NetPolicy::Deny: no IPv4, IPv6 or packet sockets.
The generated config points the egress worker's globalOutbound at a
Unix socket (Windows: in-container loopback) this launcher owns, as a
workerd external service in HTTP proxy style. Workerd then sends:
- each
fetch()as one absolute-form request (GET https://host/path), in plain text, because TLS to the origin is this relay's job; and - each
connect()socket asCONNECT host:port.
For either, the relay opens one stream on the host's CONNECT proxy link
(the same multiplexed link a native guest uses) and asks the host for a
tunnel to host:port. The host checks the tunnel against the plugin's
approved grant (crate::socket_proxy::TunnelRule::IsolateEgress),
resolves the name, checks every address, and dials. The relay then
originates TLS for https (rustls on the hosts' one provider, Mozilla's
roots), forwards the request in origin form, and splices bytes.
Nothing here widens what the plugin can reach: the host's check is the boundary, and it runs outside the jail. The relay keeps TLS and HTTP inside the jail so the unsandboxed host never parses an origin's response or sees a plugin's plaintext.
One request per connection. The relay rewrites the request to
connection: close (or keeps Upgrade for WebSockets) and rewrites the
final response head to connection: close, so workerd never sends a
second request down a tunnel opened for another origin. Interim 1xx
responses are forwarded and the next head is read, for the same reason.
Transport failures (a refused tunnel, a failed dial or TLS handshake)
close the workerd connection without a response, so the plugin's
fetch() rejects as it would on a lost connection, rather than resolving
to a synthetic status. The relay never logs URLs or headers, which carry
plugin tokens.
The parsing is sans-IO (parse_request_head, parse_response_head,
find_head_end) so the egress_relay_head fuzz target and the unit
tests drive the same code the relay runs.
| Item | Kind | Summary |
|---|---|---|
TunnelOpener |
trait | Opens one stream on the host's proxy link. |
TunnelTarget |
struct | A tunnel target: host and port, as the host proxy's CONNECT line names them. |
ResponseHead |
struct | A parsed response head from an origin. |
HeadError |
enum | Why a head was refused. |
Scheme |
enum | URL scheme of a forwarded request. |
RelayRequest |
enum | What workerd asked the relay to do with one connection. |
find_head_end |
function | Byte offset just past the \r\n\r\n that ends a head, if buf holds one. |
parse_request_head |
function | Parses the head workerd sent and decides what to do with the connection. |
parse_response_head |
function | Parses a response head from an origin and rewrites a final one. |
open_tunnel |
function | Asks the host for a tunnel to target on a fresh stream. |
host_link_from_env |
function | Opens the host's proxy link that the host delivered to this process. |
serve |
function | Accepts workerd connections and relays each through the host until the listener fails. |
MAX_HEAD_BYTES |
constant | Largest request or response head the relay buffers, in bytes. |
MAX_HEADER_LINES |
constant | Most header lines the relay accepts in one head. |
MAX_CONCURRENT_TUNNELS |
constant | Tunnels the relay keeps open at once. |
pub trait TunnelOpener: Send + Sync + 'static {
type Stream: AsyncRead + AsyncWrite + Unpin + Send + 'static;
fn open<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Self::Stream>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
}
Opens one stream on the host's proxy link.
A trait so tests can stand in for the multiplexed link.
type Stream: AsyncRead + AsyncWrite + Unpin + Send + 'static
Byte stream the host proxy answers CONNECT on.
fn open<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Self::Stream>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Opens a fresh stream to the host proxy.
When the link is closed.
Implemented by: Mux
pub struct TunnelTarget {
pub host: String,
pub port: u16,
}
A tunnel target: host and port, as the host proxy's CONNECT line names
them.
Fields
host: Lowercased host name or IP literal, without IPv6 brackets.port: Destination TCP port.
pub fn authority(&self) -> String
host:port with IPv6 literals in brackets, for a CONNECT line.
Implements: Clone, Debug, Eq, PartialEq
pub struct ResponseHead {
pub status: u16,
pub head: Vec<u8>,
}
A parsed response head from an origin.
Fields
status: HTTP status code.head: The head to hand to workerd, ending in\r\n\r\n. Interim (1xx) and101heads are unchanged; a final head is rewritten toconnection: close.
pub fn is_interim(&self) -> bool
Whether another head follows this one (an interim 1xx other than
101 Switching Protocols).
Implements: Clone, Debug, Eq, PartialEq
pub enum HeadError {
TooLarge,
BadStartLine,
BadHeader,
BadTarget,
NotText,
}
Why a head was refused.
Variants
TooLarge: The head exceedsMAX_HEAD_BYTESorMAX_HEADER_LINES.BadStartLine: The request or status line is not well formed.BadHeader: A header line is notname: value, has an invalid name, or carries a stray CR or LF, or is an obsolete folded continuation.BadTarget: The request target is not absolute-formhttp(s)://or aCONNECTauthority, or it carries userinfo or a fragment.NotText: The head is not valid UTF-8 where text is required.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub enum Scheme {
Http,
Https,
}
URL scheme of a forwarded request.
Variants
Http: Plain HTTP; the relay forwards bytes as they are.Https: HTTPS; the relay originates TLS to the origin.
pub fn default_port(self) -> u16
Port a URL without an explicit port uses.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum RelayRequest {
Tunnel(TunnelTarget),
Forward { scheme: Scheme, target: TunnelTarget, head: Vec<u8> },
}
What workerd asked the relay to do with one connection.
Variants
Tunnel: Aconnect()socket: open a tunnel and splice raw bytes.Forward: Afetch()request: open a tunnel, add TLS forhttps, then sendSelf::Forward::headfollowed by the request body as workerd sends it.scheme: Scheme of the request URL.target: Origin the request goes to.head: The rewritten head in origin form, ending in\r\n\r\n.
Implements: Clone, Debug, Eq, PartialEq
pub fn find_head_end(buf: &[u8]) -> Option<usize>
Byte offset just past the \r\n\r\n that ends a head, if buf holds one.
buf- Bytes read so far.
Some(n) where buf[..n] is the head, or None when more bytes are
needed.
pub fn parse_request_head(head: &[u8]) -> Result<RelayRequest, HeadError>
Parses the head workerd sent and decides what to do with the connection.
head- The complete request head, through\r\n\r\n(find_head_end).
RelayRequest::Tunnel for CONNECT host:port, or
RelayRequest::Forward with the head rewritten to origin form: host
set from the URL, proxy and hop-by-hop headers dropped, and connection: close (or connection: upgrade when the request carries upgrade).
HeadError when the head is malformed or the target is not an absolute
http/https URL or a CONNECT authority.
pub fn parse_response_head(head: &[u8]) -> Result<ResponseHead, HeadError>
Parses a response head from an origin and rewrites a final one.
head- The complete response head, through\r\n\r\n.
The status and the head to hand to workerd: interim and 101 heads
unchanged, a final head with its connection headers replaced by
connection: close.
HeadError when the status line or a header is malformed.
pub async fn open_tunnel<O: TunnelOpener>(
opener: &O,
target: &TunnelTarget,
) -> Result<<O as >::Stream>
Asks the host for a tunnel to target on a fresh stream.
opener- Opens streams on the host's proxy link.target- Where the tunnel should go.
The stream, now carrying the tunnel's bytes.
When the stream cannot be opened, the host refuses (any status but 200), or the host does not answer within 30 seconds.
pub async fn host_link_from_env() -> Result<Option<Arc<Mux>>>
Opens the host's proxy link that the host delivered to this process.
The host passes the link in bookclerk_sandbox::WORKERD_EGRESS_ENV
(plus bookclerk_sandbox::WORKERD_EGRESS_WRITE_ENV on Windows) and the
session challenge in bookclerk_plugin_sdk::SESSION_CHALLENGE_ENV. The
challenge is written first, then the link is multiplexed. The challenge is
removed from this process's environment once read, so a child (workerd)
never inherits it.
None when no link was delivered: the plugin's network is denied.
When the link spec or challenge is malformed, or writing the challenge fails.
pub async fn serve<A, F, C, O>(
accept: A,
opener: Arc<O>,
tls: Arc<ClientConfig>,
) -> Result<()>
where
A: FnMut() -> F,
F: Future<Output = Result<C>>,
C: AsyncRead + AsyncWrite + Unpin + Send + 'static,
O: TunnelOpener,
Accepts workerd connections and relays each through the host until the listener fails.
accept- Yields the next workerd connection.opener- Opens streams on the host's proxy link.tls- Client TLS settings forhttpsorigins.
When accepting fails; individual connections fail on their own.
pub const MAX_HEAD_BYTES: usize = _;
Largest request or response head the relay buffers, in bytes.
Workers URLs may be up to 16 KiB; headers add more. Anything larger is refused rather than buffered.
pub const MAX_HEADER_LINES: usize = 128;
Most header lines the relay accepts in one head.
pub const MAX_CONCURRENT_TUNNELS: usize = 16;
Tunnels the relay keeps open at once.
Matches the host proxy's per-link handler cap, so a burst of fetch()
calls waits here for a free tunnel instead of being dropped by the host.
Generated from crates/bookclerk-workerd at main · View as Markdown