10.2 rpc attributes
| Attribute | Where it acts | Semantics |
|---|---|---|
@timeout(d) | client and server | the default call deadline; the server clamps a larger client deadline to d |
@retry(n, backoff: b) | client | retry on Timeout | Unavailable; allowed only together with @idempotent or @readonly, otherwise a compile error |
@idempotent(key: f) | server | the response is stored in the built-in storage under the key f(request) for ttl (by default the cluster's IDEMPOTENCY_TTL); a repeat returns the stored response |
@readonly | contract | the method does not change state; permits @retry and @cache |
@cache(ttl: d, key: f?) | server | response cache; only with @readonly |
@ratelimit(rps: n, burst: m, by: f) | server | rate limiting; exceeding it gives Unavailable with a retry-after hint |
@public | access | a call without a policy (§13.4) |
@allow(…) | access | a short inline policy (§13.4) |
@resumable | stream | resuming a stream by offset (§10.3) |
@window(n) | stream | credit window, 64 messages by default |
@trace(sample: p), @audit | observability | §15.5, §13.4 |
Defaults for all rpcs are set in cluster { defaults { … } } (§12.1).
User attributes and Middleware (D-8052; DIV-010; D-7530, D-7531). attr Name { fields } declares an ordinary data type; @Name(args) on a service rpc builds the value Name{args} (named or positional arguments). A type that implements
@explicit interface Middleware { fn around(ctx: &var Ctx, next: Next) -> Response net, io, time, db }wraps the handler on the server side:
- the interface permits the effects
net, io, time, db; a concrete implementation ofaroundMAY declare fewer (for example, onlynet); Next = fn(&var Ctx) -> Response net;Response { error: NetError?, passed: bool }is a token of the call passing through, not a result value:Response.refuse(e)terminates the call with the errorNetErrorwithout executing the handler; aResponsereturned without callingnextand without an error is aProtocolErrorwith code 13. A middleware cannot replace the typed result — it stays with the handler; the handler's error passes through unchanged;- attributes nest in the order written (the first is the outermost); the other rpc attributes (
@timeout,@cache, …) wrap the whole handler. A user attribute may be repeated, built-in ones may not.
Implementation-defined. Scope of
Middleware(D-8052; DIV-010; D-7530). Optional features: middleware on the client side and on streaming rpcs (in this implementation the attribute on a streaming rpc is accepted but wraps nothing); changes toctxmade by a middleware do not reach the handler's ownctx.
Related diagnostics
attribute-not-applicable, cache-not-readonly, invalid-window, retry-not-idempotent, rpc-attr
See also
Source: docs/spec/oxl-standard.en.md