bookclerk_plugin_abi::origin
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. |
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
pub struct IngressOrigin(/* private */);
The public origin an ingress plugin serves: https:// and a lowercase
DNS host name, nothing else.
pub fn as_str(&self) -> &str
The origin as text, https://<host>.
pub fn host(&self) -> &str
The host name, without the scheme.
Implements: Clone, Debug, Display, Eq, Hash, PartialEq
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
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.
request- The head as the guest sent it.
The method, target and client address as checked, and the headers
without host and forwarding fields.
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.
pub fn check_origin_response(status: u16, headers: &[OriginHeader]) -> Result<()>
Checks the head of a response the host sends back to a relay plugin.
PluginError::invalid_params when the status is outside 100 to 599
or a header breaks a rule.
pub fn parse_ingress_origin(started: &IngressStarted) -> Result<IngressOrigin>
Parses the public origin an ingress plugin reports from start.
started- The plugin's answer.
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.
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.
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.
internal when the head does not encode or is larger than
MAX_ORIGIN_FRAME_HEAD_BYTES.
pub fn split_origin_frame(buf: &[u8]) -> Result<Option<(&[u8], &[u8])>>
Splits a framed head off the front of buf.
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).
invalid_params when the declared length exceeds
MAX_ORIGIN_FRAME_HEAD_BYTES, so a guest cannot make the host buffer
without bound.
pub fn decode_origin_request_frame(json: &[u8]) -> Result<CheckedOriginRequest>
Decodes and checks a framed request head from an isolate.
invalid_params when the JSON is not an OriginRequest or the head
fails check_origin_request.
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).
invalid_params when the JSON is not a head or fails
check_origin_response.
pub const MAX_ORIGIN_METHOD_BYTES: usize = 32;
Longest request method, in bytes.
pub const ORIGIN_FRAME_PREFIX_BYTES: usize = 4;
Bytes of the length prefix in front of a framed head.
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