bookclerk_plugin_sdk::http
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. |
redirect: Redirect follow policy (reqwest-compatible names).
pub trait IntoUrlArg {
fn into_url_arg(self) -> String;
}
Something Client::get / Client::request can target.
fn into_url_arg(self) -> String
Owned URL string.
Implemented by: &str, &String, &Url, String, Url
pub struct Error(/* private */);
Errors from Client / RequestBuilder.
pub fn is_timeout(&self) -> bool
True when the message looks like a timeout (retry hint).
pub fn is_connect(&self) -> bool
True when the message looks like a connect/DNS failure (retry hint).
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>
pub struct CookieJar {
/* private fields */
}
Shared cookie jar (reqwest path + proxied cookie_store).
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
pub struct ClientBuilder {
/* private fields */
}
Builder for Client.
pub fn new() -> Self
Empty builder (10-hop redirects, no cookies).
pub fn timeout(self, timeout: Duration) -> Self
Overall request timeout (connect + headers + body).
pub fn connect_timeout(self, timeout: Duration) -> Self
CONNECT / TCP timeout (ambient reqwest path).
pub fn read_timeout(self, timeout: Duration) -> Self
Alias for Self::timeout (audible-rs read_timeout).
pub fn user_agent(self, value: impl Into<String>) -> Self
Default User-Agent.
pub fn cookie_store(self, enable: bool) -> Self
Enable reqwest / proxied cookie jars (separate stores; one process is either proxied or ambient).
pub fn cookie_provider(self, jar: Arc<CookieJar>) -> Self
Shared jar for Magento-style login + follow-up clients.
pub fn redirect(self, policy: Policy) -> Self
Redirect policy.
pub fn default_headers(self, headers: HeaderMap) -> Self
Default headers merged into every request (request wins on conflict).
pub fn no_gzip(self) -> Self
Do not advertise gzip/br/deflate (CloudFront CENC URLs 403 on those).
pub fn no_brotli(self) -> Self
See Self::no_gzip.
pub fn no_deflate(self) -> Self
See Self::no_gzip.
pub fn build(self) -> HttpResult<Client>
Builds the client.
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
pub struct Client {
/* private fields */
}
HTTP client: ambient reqwest, or CONNECT+rustls through the socket proxy.
pub fn new() -> Self
Default client (ambient or proxied from env).
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.
pub fn builder() -> ClientBuilder
Builder.
pub fn get(&self, url: impl IntoUrlArg) -> RequestBuilder
GET.
pub fn post(&self, url: impl IntoUrlArg) -> RequestBuilder
POST.
pub fn put(&self, url: impl IntoUrlArg) -> RequestBuilder
PUT.
pub fn delete(&self, url: impl IntoUrlArg) -> RequestBuilder
DELETE.
pub fn request(&self, method: Method, url: impl IntoUrlArg) -> RequestBuilder
Arbitrary method.
Implements: Clone, Debug, Default
pub struct RequestBuilder {
/* private fields */
}
In-flight request.
pub fn header<K, V>(self, key: K, value: V) -> Self
where
HeaderName: TryFrom<K>,
HeaderValue: TryFrom<V>,
Extra header.
pub fn headers(self, headers: HeaderMap) -> Self
Merge headers (existing keys on self win).
pub fn bearer_auth(self, token: impl AsRef<str>) -> Self
Authorization: Bearer.
pub fn json<T: Serialize>(self, value: &T) -> Self
JSON body + Content-Type.
pub fn form<T: Serialize>(self, value: &T) -> Self
application/x-www-form-urlencoded.
pub fn body(self, body: impl Into<Vec<u8>>) -> Self
Raw body bytes.
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.
pub fn timeout(self, timeout: Duration) -> Self
Per-request timeout override.
pub async fn send(self) -> HttpResult<Response>
Dispatch.
Returns when the URL is invalid, CONNECT/TLS fails, or the origin errors.
pub struct Response {
/* private fields */
}
Origin response.
pub fn status(&self) -> StatusCode
HTTP status.
pub fn headers(&self) -> &HeaderMap
Response headers (after cookie extraction on the proxied path).
pub fn url(&self) -> &Url
Final URL after redirects.
pub fn content_length(&self) -> Option<u64>
Content-Length when the origin sent a valid header.
pub fn error_for_status(self) -> HttpResult<Self>
Fail on 4xx/5xx.
Returns when the status is a client or server error.
pub async fn bytes(self) -> HttpResult<Bytes>
Entire body.
Returns on I/O or decode failure.
pub async fn text(self) -> HttpResult<String>
UTF-8 body (lossy).
Returns on I/O failure.
pub async fn json<T: DeserializeOwned>(self) -> HttpResult<T>
JSON body.
Returns on I/O or JSON decode failure.
pub async fn chunk(&mut self) -> HttpResult<Option<Bytes>>
Next body chunk (download loops).
Returns on I/O failure.
pub fn bytes_stream(self) -> ByteStream
Streaming body (audible-rs / throttled downloads).
pub struct ByteStream {
/* private fields */
}
Stream of body chunks from Response::bytes_stream.
Implements: Stream
pub async fn connect_tls(address: SocketAddress) -> Result<TlsStream<ProxyStream>>
CONNECT then rustls to address (HTTPS origins).
Returns when the proxy is missing, CONNECT is denied, or TLS fails.
pub type HttpResult<T> = Result<T, Error>;
Result alias for guest HTTP.
Generated from crates/bookclerk-plugin-sdk at main · View as Markdown