[jwrosewell]

Summary

• Let a middleware prepare with the request's services and refuse a request.
• Row 23 of the stack listed in the pluggable modules issue (Pluggable, competition-neutral modules with a technical permission model #777), on feature/22-creating. James Rogers (Jamesr51d) approved this change at d9fb81a on the fork's pull request A middleware may prepare, with the request's services, and may refuse jwrosewell/trusted-server#18, closed when the review moved here.

Changes

Area	Change
crates/trusted-server-core/src	8 files, 1438 lines added, 63 removed
docs/guide	1 file, 55 lines added, 0 removed
CHANGELOG.md	1 file, 1 line added, 0 removed
crates/trusted-server-core/benches	1 file, 1 line added, 0 removed

Closes

Closes #1281

Spec

Spec: middleware-prepare

Test plan

CI on this pull request at 06ca813 passed all 32 checks.

• cargo test-fastly && cargo test-axum
• cargo clippy-fastly && cargo clippy-axum
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run
• JS format: cd crates/trusted-server-js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Manual testing via fastly compute serve
• Other: the full workflow set of this repository, run on this pull request at 06ca813

Checklist

• Changes follow AGENTS.md conventions
• No unwrap() in production code (clippy denies unwrap_used in CI)
• Uses log macros as AGENTS.md asks (not println!)
• New code has tests
• No secrets or credentials committed

---

Stacks on making a file the origin does not have (#1363).

What this pull request does

A middleware whose decision needs the request's services, or has to wait on the store or the network, answers Middleware::prepare with a future. The request's handler runs it before the document is processed, as the middleware's module with the permissions it declares, and what it answers is kept under the middleware's name and phase for create in that phase to take.

fn prepare<'a>(&'a self, call: ModuleCall<'a>, context: &'a MiddlewareContext<'a>) -> Option<Preparation<'a>> {

    Some(Box::pin(async move {

        let lines = self.lines_for(call, context.request_host).await?;

        Ok(Box::new(lines) as Box<dyn Any + Send>)

    }))

}

fn create(&self, context: &MiddlewareContext<'_>) -> MiddlewareAction {

    let lines: Vec<String> = context.take_prepared(MODULE).unwrap_or_default();

    MiddlewareAction { stream: Some(Box::new(AppendLines::new(lines))), ..MiddlewareAction::pass() }

}

A preparation may answer a Refusal instead, with a status, an optional Retry-After in whole seconds rounded up, and a message, and the request is answered with that status, no document is processed, and nothing is stored or served from the store.

Why

create is synchronous, is given no services, and is asked inside the synchronous streaming paths that the Fastly adapter needs. A middleware that makes a well known file from what the store holds or a service answers, as robots.txt does, could not decide there, and could not fail closed when it had nothing to give, which for robots.txt matters because an empty file tells crawlers to crawl everything. The preparation runs where the handler is asynchronous on every adapter, and only its answer, a Send value, travels to the streaming paths, so create, the plan and every streaming path are as they were.

The rules

• A middleware that prepares nothing is asked create as before, and nothing of it changes.

• On a document fetched for the request that will not be stored, both phases are prepared, fetch then serve. On a document that may be stored, both phases are prepared too, so the serve middleware of the reader it was fetched for find what they prepared. The fetch phase is handed the request's services and nothing of the reader, and the serve phase is handed the reader's state. On a copy read from the store, the serve phase alone. The preparations of a phase run in the order the entry names the middleware.

• The first refusal ends the preparations of a document, and the response it makes is marked private and unstorable.

• A fetch preparation of a document that may be stored is handed the request's services and nothing of the reader, neither its permissions, location nor Edge Cookie, because its answer is stored with the document.

What breaks

MiddlewareContext, HtmlProcessorConfig and ReaderDocument each gain a required pub field prepared, so every struct literal of them outside this repository stops compiling.

How it was verified

Not exercised: no preparation has run against a real store or network, because the fixtures answer from what they are called with. The preparation on a copy read from the store has no test, because the test services have no template cache.

References #1281.