bookclerk_plugin_abi::origin

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

Last updated View as Markdown

Sans-IO checks for the ORIGIN binding and the ingress entrypoint.

A relay ingress plugin hands the host the head of every public request it carries (OriginRequest) and, when it starts, the public origin it serves (IngressStarted). Both come from a guest, so the host checks them here before anything reaches the router or the database; the host checks the response head it sends back the same way. Keeping the rules over plain values lets the fuzz target and the unit tests drive the code the host runs.

Item Kind Summary
CheckedOriginRequest struct A checked OriginRequest: what the host dispatches into the router.
IngressOrigin struct The public origin an ingress plugin serves: https:// and a lowercase DNS host name, nothing else.
OriginResponseHead struct The head of the library's response to one origin request, as the isolate bridge frames it (encode_origin_frame).
check_origin_request function Checks the head of one public request a relay plugin carries and keeps what the host passes on.
check_origin_response function Checks the head of a response the host sends back to a relay plugin.
parse_ingress_origin function Parses the public origin an ingress plugin reports from start.
encode_origin_frame function Frames head for the isolate bridge: a 4-byte big-endian length, then the head as JSON. The body follows the frame on the same stream.
split_origin_frame function Splits a framed head off the front of buf.
decode_origin_request_frame function Decodes and checks a framed request head from an isolate.
decode_origin_response_frame function Decodes and checks a framed response head (the isolate side reads these; the host only writes them, so this is for tests and fuzzing).
MAX_ORIGIN_METHOD_BYTES constant Longest request method, in bytes.
ORIGIN_FRAME_PREFIX_BYTES constant Bytes of the length prefix in front of a framed head.
MAX_ORIGIN_FRAME_HEAD_BYTES constant Largest framed head on the isolate bridge's origin route: the JSON of a head at its limits, with room for escaping every header byte and the target.

Structs

CheckedOriginRequest

pub struct CheckedOriginRequest {
    pub method: String,
    pub target: String,
    pub headers: Vec<OriginHeader>,
    pub client: Option<IpAddr>,
}

A checked [OriginRequest]: what the host dispatches into the router.

Fields

  • method: Request method, an HTTP token, as sent.
  • target: Path and query in origin form.
  • headers: Header fields in order, without the ignored ones.
  • client: The client's IP address, when the provider reported one.

Implements: Clone, Debug, Eq, PartialEq

IngressOrigin

pub struct IngressOrigin(/* private */);

The public origin an ingress plugin serves: https:// and a lowercase DNS host name, nothing else.

IngressOrigin::as_str

pub fn as_str(&self) -> &str

The origin as text, https://<host>.

IngressOrigin::host

pub fn host(&self) -> &str

The host name, without the scheme.

Implements: Clone, Debug, Display, Eq, Hash, PartialEq

OriginResponseHead

pub struct OriginResponseHead {
    pub status: u16,
    pub headers: Vec<OriginHeader>,
}

The head of the library's response to one origin request, as the isolate bridge frames it (encode_origin_frame).

Fields

  • status: HTTP status code, 100 to 599.
  • headers: Response header fields in order.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

Functions

check_origin_request

pub fn check_origin_request(request: &OriginRequest) -> Result<CheckedOriginRequest>

Checks the head of one public request a relay plugin carries and keeps what the host passes on.

Arguments

  • request - The head as the guest sent it.

Returns

The method, target and client address as checked, and the headers without host and forwarding fields.

Errors

PluginError::invalid_params when the method is not a token, the target is not origin form or too long, a header breaks a rule, or the client address is not an IP address.

check_origin_response

pub fn check_origin_response(status: u16, headers: &[OriginHeader]) -> Result<()>

Checks the head of a response the host sends back to a relay plugin.

Errors

PluginError::invalid_params when the status is outside 100 to 599 or a header breaks a rule.

parse_ingress_origin

pub fn parse_ingress_origin(started: &IngressStarted) -> Result<IngressOrigin>

Parses the public origin an ingress plugin reports from start.

Arguments

  • started - The plugin's answer.

Returns

The origin, https:// and a lowercase host name of at least two labels, at most maxIngressOriginBytes; the top label starts with a letter, so nothing a URL parser reads as an IP address passes.

Errors

PluginError::invalid_params for any other scheme, a port, path, query, user info, trailing dot or slash, uppercase, or a host that is not a DNS name.

encode_origin_frame

pub fn encode_origin_frame<T: Serialize>(head: &T) -> Result<Vec<u8>>

Frames head for the isolate bridge: a 4-byte big-endian length, then the head as JSON. The body follows the frame on the same stream.

Errors

internal when the head does not encode or is larger than MAX_ORIGIN_FRAME_HEAD_BYTES.

split_origin_frame

pub fn split_origin_frame(buf: &[u8]) -> Result<Option<(&[u8], &[u8])>>

Splits a framed head off the front of buf.

Returns

Ok(None) while buf holds less than the whole frame; otherwise the head's JSON and the bytes after it (the start of the body).

Errors

invalid_params when the declared length exceeds MAX_ORIGIN_FRAME_HEAD_BYTES, so a guest cannot make the host buffer without bound.

decode_origin_request_frame

pub fn decode_origin_request_frame(json: &[u8]) -> Result<CheckedOriginRequest>

Decodes and checks a framed request head from an isolate.

Errors

invalid_params when the JSON is not an OriginRequest or the head fails check_origin_request.

decode_origin_response_frame

pub fn decode_origin_response_frame(json: &[u8]) -> Result<OriginResponseHead>

Decodes and checks a framed response head (the isolate side reads these; the host only writes them, so this is for tests and fuzzing).

Errors

invalid_params when the JSON is not a head or fails check_origin_response.

Constants

MAX_ORIGIN_METHOD_BYTES

pub const MAX_ORIGIN_METHOD_BYTES: usize = 32;

Longest request method, in bytes.

ORIGIN_FRAME_PREFIX_BYTES

pub const ORIGIN_FRAME_PREFIX_BYTES: usize = 4;

Bytes of the length prefix in front of a framed head.

MAX_ORIGIN_FRAME_HEAD_BYTES

pub const MAX_ORIGIN_FRAME_HEAD_BYTES: usize = _;

Largest framed head on the isolate bridge's origin route: the JSON of a head at its limits, with room for escaping every header byte and the target.

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