bookclerk_plugin_sdk::http

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

Last updated View as Markdown

Native guest HTTP through the workerd socket proxy.

When crate::SOCKET_PROXY_ENV is unset (crate tests, host-owned D1), this module wraps reqwest::Client over ambient TCP. When the proxy is set, every request is CONNECT + rustls over the Unix or Windows named-pipe proxy — nested NetPolicy::Deny guests must not call socket(AF_INET). When crate::NESTED_NATIVE_JAIL_ENV is 1 without a proxy, construction fails closed rather than falling back to ambient TCP.

While the host sets crate::USER_AGENT_ENV, every request hop carries the host's User-Agent unless its host is one the operator approved in crate::OWN_USER_AGENT_HOSTS_ENV and the guest set its own agent.

Fetch domain grants do not imply TCP. Native manifests must declare capabilities.network.tcp (or rely on a host overlay) for each host:port this client dials.

Item Kind Summary
IntoUrlArg trait Something Client::get / Client::request can target.
Error struct Errors from Client / RequestBuilder.
CookieJar struct Shared cookie jar (reqwest path + proxied cookie_store).
ClientBuilder struct Builder for Client.
Client struct HTTP client: ambient reqwest, or CONNECT+rustls through the socket proxy.
RequestBuilder struct In-flight request.
Response struct Origin response.
ByteStream struct Stream of body chunks from Response::bytes_stream.
connect_tls function CONNECT then rustls to address (HTTPS origins).
HttpResult type alias Result alias for guest HTTP.

Re-exports

Modules

  • redirect: Redirect follow policy (reqwest-compatible names).

Traits

IntoUrlArg

pub trait IntoUrlArg {
    fn into_url_arg(self) -> String;
}

Something Client::get / Client::request can target.

IntoUrlArg::into_url_arg

fn into_url_arg(self) -> String

Owned URL string.

Implemented by: &str, &String, &Url, String, Url

Structs

Error

pub struct Error(/* private */);

Errors from Client / RequestBuilder.

Error::is_timeout

pub fn is_timeout(&self) -> bool

True when the message looks like a timeout (retry hint).

Error::is_connect

pub fn is_connect(&self) -> bool

True when the message looks like a connect/DNS failure (retry hint).

Error::is_request

pub fn is_request(&self) -> bool

True when the error is a transport-class failure worth retrying.

Implements: Debug, Display, Error, From<Error>, From<ParseError>, From<SdkError>

CookieJar

pub struct CookieJar {
    /* private fields */
}

Shared cookie jar (reqwest path + proxied cookie_store).

CookieJar::new

pub fn new() -> Arc<Self>

Empty jar shared across clients in one guest process.

pub fn add_cookie_str(&self, cookie: &str, url: &Url)

Seeds a Set-Cookie line (Amazon login init cookies).

Implements: Clone, Default

ClientBuilder

pub struct ClientBuilder {
    /* private fields */
}

Builder for Client.

ClientBuilder::new

pub fn new() -> Self

Empty builder (10-hop redirects, no cookies).

ClientBuilder::timeout

pub fn timeout(self, timeout: Duration) -> Self

Overall request timeout (connect + headers + body).

ClientBuilder::connect_timeout

pub fn connect_timeout(self, timeout: Duration) -> Self

CONNECT / TCP timeout (ambient reqwest path).

ClientBuilder::read_timeout

pub fn read_timeout(self, timeout: Duration) -> Self

Alias for Self::timeout (audible-rs read_timeout).

ClientBuilder::user_agent

pub fn user_agent(self, value: impl Into<String>) -> Self

Default User-Agent.

ClientBuilder::cookie_store

pub fn cookie_store(self, enable: bool) -> Self

Enable reqwest / proxied cookie jars (separate stores; one process is either proxied or ambient).

ClientBuilder::cookie_provider

pub fn cookie_provider(self, jar: Arc<CookieJar>) -> Self

Shared jar for Magento-style login + follow-up clients.

ClientBuilder::redirect

pub fn redirect(self, policy: Policy) -> Self

Redirect policy.

ClientBuilder::default_headers

pub fn default_headers(self, headers: HeaderMap) -> Self

Default headers merged into every request (request wins on conflict).

ClientBuilder::no_gzip

pub fn no_gzip(self) -> Self

Do not advertise gzip/br/deflate (CloudFront CENC URLs 403 on those).

ClientBuilder::no_brotli

pub fn no_brotli(self) -> Self

See Self::no_gzip.

ClientBuilder::no_deflate

pub fn no_deflate(self) -> Self

See Self::no_gzip.

ClientBuilder::build

pub fn build(self) -> HttpResult<Client>

Builds the client.

Errors

Returns when nested Deny is set without a socket proxy, when the ambient reqwest client cannot be constructed, or when the proxied rustls config fails.

Implements: Clone, Default

Client

pub struct Client {
    /* private fields */
}

HTTP client: ambient reqwest, or CONNECT+rustls through the socket proxy.

Client::new

pub fn new() -> Self

Default client (ambient or proxied from env).

Panics

Panics when crate::SOCKET_PROXY_ENV or nested Deny is in force and the proxied client cannot be built. Does not fall back to ambient TCP. Ambient reqwest construction failure without those env vars also panics only if the last-resort reqwest::Client::new cannot be created.

Every call in one plugin process hands out a clone of the same client, so its requests share one connection pool and reuse TLS connections instead of handshaking per call. That client holds no cookie jar and no default headers, so sharing it carries nothing from one request (or account) to the next; a client that needs cookies or its own headers is built with Client::builder and keeps its own pool. The sharing never crosses processes, so it never crosses a plugin's sandbox.

Client::builder

pub fn builder() -> ClientBuilder

Builder.

Client::get

pub fn get(&self, url: impl IntoUrlArg) -> RequestBuilder

GET.

Client::post

pub fn post(&self, url: impl IntoUrlArg) -> RequestBuilder

POST.

Client::put

pub fn put(&self, url: impl IntoUrlArg) -> RequestBuilder

PUT.

Client::delete

pub fn delete(&self, url: impl IntoUrlArg) -> RequestBuilder

DELETE.

Client::request

pub fn request(&self, method: Method, url: impl IntoUrlArg) -> RequestBuilder

Arbitrary method.

Implements: Clone, Debug, Default

RequestBuilder

pub struct RequestBuilder {
    /* private fields */
}

In-flight request.

RequestBuilder::header

pub fn header<K, V>(self, key: K, value: V) -> Self
where
    HeaderName: TryFrom<K>,
    HeaderValue: TryFrom<V>,

Extra header.

RequestBuilder::headers

pub fn headers(self, headers: HeaderMap) -> Self

Merge headers (existing keys on self win).

RequestBuilder::bearer_auth

pub fn bearer_auth(self, token: impl AsRef<str>) -> Self

Authorization: Bearer.

RequestBuilder::json

pub fn json<T: Serialize>(self, value: &T) -> Self

JSON body + Content-Type.

RequestBuilder::form

pub fn form<T: Serialize>(self, value: &T) -> Self

application/x-www-form-urlencoded.

RequestBuilder::body

pub fn body(self, body: impl Into<Vec<u8>>) -> Self

Raw body bytes.

RequestBuilder::query

pub fn query<T: Serialize>(self, query: &T) -> Self

Query string pairs (serde_urlencoded).

Values are decoded after serde_urlencoded so the URL encoder emits them once (reqwest-compatible). Storing the encoded form would turn , into %252C and Audible catalog search into HTTP 400.

RequestBuilder::timeout

pub fn timeout(self, timeout: Duration) -> Self

Per-request timeout override.

RequestBuilder::send

pub async fn send(self) -> HttpResult<Response>

Dispatch.

Errors

Returns when the URL is invalid, CONNECT/TLS fails, or the origin errors.

Response

pub struct Response {
    /* private fields */
}

Origin response.

Response::status

pub fn status(&self) -> StatusCode

HTTP status.

Response::headers

pub fn headers(&self) -> &HeaderMap

Response headers (after cookie extraction on the proxied path).

Response::url

pub fn url(&self) -> &Url

Final URL after redirects.

Response::content_length

pub fn content_length(&self) -> Option<u64>

Content-Length when the origin sent a valid header.

Response::error_for_status

pub fn error_for_status(self) -> HttpResult<Self>

Fail on 4xx/5xx.

Errors

Returns when the status is a client or server error.

Response::bytes

pub async fn bytes(self) -> HttpResult<Bytes>

Entire body.

Errors

Returns on I/O or decode failure.

Response::text

pub async fn text(self) -> HttpResult<String>

UTF-8 body (lossy).

Errors

Returns on I/O failure.

Response::json

pub async fn json<T: DeserializeOwned>(self) -> HttpResult<T>

JSON body.

Errors

Returns on I/O or JSON decode failure.

Response::chunk

pub async fn chunk(&mut self) -> HttpResult<Option<Bytes>>

Next body chunk (download loops).

Errors

Returns on I/O failure.

Response::bytes_stream

pub fn bytes_stream(self) -> ByteStream

Streaming body (audible-rs / throttled downloads).

ByteStream

pub struct ByteStream {
    /* private fields */
}

Stream of body chunks from Response::bytes_stream.

Implements: Stream

Functions

connect_tls

pub async fn connect_tls(address: SocketAddress) -> Result<TlsStream<ProxyStream>>

CONNECT then rustls to address (HTTPS origins).

Errors

Returns when the proxy is missing, CONNECT is denied, or TLS fails.

Type aliases

HttpResult

pub type HttpResult<T> = Result<T, Error>;

Result alias for guest HTTP.

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