Download the PHP package rapira/contract without Composer

rapira/contract

PHP-side contract for Rapira, a PHP application server written in Rust. PHP is embedded in the server process — no FastCGI, no sockets, no serialization. This package declares the types that boundary speaks; the extension provides the objects.

Requires PHP 8.4 — the extension's floor; the stubs themselves use nothing newer than 8.2. Execution modes form a ladder — Rapira\Mode, read back at runtime from get_mode(): Classic boots the script per request, Worker boots it once and serves requests one after another through the SAPI superglobals, Dispatcher takes requests as units of work through this contract — one at a time or concurrently on fibers. Only Dispatcher mode has a dispatcher; everything below lives on that rung.

Contract

Plugins narrow receive() natively and add their own finalization verbs. Each plugin's surface, and the reasoning behind its shape, lives beside its stubs:

• Rapira\Http — the request/response exchange, framing, content coding.
• Rapira\Grpc — the call and its responder, streams, statuses, metadata.

Rules

• PHP pulls, the host never pushes. The loop belongs to userland; without it there is no scheduler, no work between units, no event loop integration.
• Config flows TOML → host → PHP. PHP discovers what it serves and never parameterizes a plugin.
• One spelling per fact: null is "nothing at this moment", ClosedException is "no more work, ever", TimeoutException is "the wait elapsed". No value carries two meanings.
• At capacity receive() waits and tryReceive() returns null — backpressure, not an error. Same behaviour at one unit in flight and at N.
• The current host holds one unit per worker at a time: receive() and tryReceive() throw \Error while that unit is unfinalized, and a wait blocks the thread. Several units in flight, with waits that suspend the fiber, is the target; an SDK must not depend on it yet.
• Waiting suspends the calling fiber, not the thread; outside a fiber it blocks the process, because the main context cannot be suspended. Who resumes a suspended fiber is the PHP wrapper's business, never this contract's: the contract names its suspension points — receive(), a MessageStream step, a streaming drain — and never names a scheduler.
• Finalization verbs live on the unit and are per-plugin. Work carries only the two facts a generic layer cannot compute for itself.
• Addresses are the union InetAddress|UnixAddress, mirroring Pingora's own SocketAddr: a unix listener has no IP and its connecting peer usually no name at all, so "a port exists" is a fact the type states — not a zero sentinel carrying two meanings. They live in Rapira\: HTTP and gRPC both put them on their request shapes, and what plugins share, the root holds.
• Each plugin owns a first-level namespace: Rapira\Http, Rapira\Grpc, later Rapira\Jobs. Rapira\ holds only what they share — Dispatcher, Work, DispatcherInfo, LogLevel, the address types, Tls, the functions — and Rapira\Exception\ only the exceptions more than one plugin can throw. A plugin's own live the same way, in its own Exception\ sub-namespace — Http\Exception\HeadAlreadyWrittenError — one rule for where a throwable lives, whichever surface throws it. A refinement of a type is a sibling, not a child: Grpc\StreamingRequest extends Grpc\Call in the same namespace — a subtype is a way the parent comes, not something it hands out. A directory under a type's name holds only the shapes that type alone hands out — Grpc\Call\Context exists through Call::getContext() and nothing else — while what worker code constructs itself, Status and the boot-time descriptors, stays at the plugin root: the directory answers who gives you the object.
• Unfinalized units are the host's problem: it fails them and recycles the worker per pool policy.
• Cancellation is cooperative. VM interrupts are a pool watchdog, not routine cancellation, and cannot fire while PHP is inside a blocking native call.
• Interface members are methods, not hooked properties — internal classes cannot declare hooks, and the stub generator has no syntax for them.
• Behaviour is an interface, data is a final readonly class with a public constructor. So every type is either mockable or constructible, and a test never needs the host: a fake StreamingRequest returns an array-backed MessageStream, a fixture Context carries a new Metadata([...]).
• The global functions cannot be redeclared per test, so without the extension each stub delegates to an Internal\Runtime, whose own answers are the fallbacks: Classic, no dispatcher, no worker requests. A test double extends it and is put in place with Internal\Double::setRuntime(); scripted doubles and test tooling live in rapira/testing.
• The consumer is Rapira's SDK, not application code. Test for any addition: could the SDK compute it itself? Then it does not belong here — unless the fact lives in the type system: an SDK can wrap next() into an iterable value, but only MessageStream itself can pass an iterable parameter.
• Interfaces state behaviour, not the reasoning behind it. Why something is shaped the way it is, or absent, is recorded here.

Exceptions

Rapira\Exception\TimeoutException and Rapira\Exception\ClosedException are both caught routinely — the first by a loop doing periodic chores, the second as the loop's exit — so both need types. They extend the SPL class that fits (\RuntimeException) and implement the Rapira\Exception\RapiraThrowable marker, so "anything from Rapira" is catchable without forcing every error into one hierarchy. The marker is named for what it spans: the \Error classes below implement it too, which makes it a supervisor's catch at the top of the worker, never a handler's.

AlreadyFinalizedError extends \Error — nobody catches it, the script fatals, the host cleans up. Not \LogicException, which frameworks catch broadly enough to swallow it. The error/exception split is left to the native hierarchy, so instanceof \Error keeps meaning "your code is wrong" and no second marker is needed for it. NoDispatcherError and NotInWorkerModeError are the same shape: a script asking for a dispatcher or for the next request in a mode that does not provide it is wrong by construction.

WorkDiscardedException is finalizing a unit the host had already closed — expired deadline, drain, gone client, lease lost to another worker. The worker broke no rule, so it is a runtime exception and not an error, and a handler catches it to log the loss. Polling Work::isCancelled() at checkpoints avoids getting there at all.

Not in the contract

Open

1. Non-dispatcher plugins. A logger richer than log() — its own target, its own sink — or a KV client is not a stream of work units and needs a second acquisition path, without bringing back config objects.

References

• rapira-rs/rapira#38 — plugin handler API; its config-object direction was superseded within its own thread.
• rapira-rs/rapira#45 — dispatcher interfaces; origin of the pull model and the finalization discipline.