pub struct PostOffice { /* private fields */ }Expand description
The messaging client. Cheap to clone; holds a handle to the Platform.
Implementations§
Source§impl PostOffice
impl PostOffice
pub fn new(platform: &Platform) -> Self
Sourcepub async fn send(&self, event: EventEnvelope) -> Result<(), AppError>
pub async fn send(&self, event: EventEnvelope) -> Result<(), AppError>
Fire-and-forget delivery to event.to (Java po.send).
Errors: 400 when to is missing, 404 when the route is not registered.
Awaits when the route’s bounded manager mailbox is full — reactive
back-pressure, not drops.
When called from inside a traced function, the platform propagates the trace automatically: the outbound event carries the current trace id/path, this function’s span id (the receiver’s parent span), the sender route, and the business correlation-id when the event has none.
A route declared in yaml.event.over.http forwards transparently to
the peer’s /api/event instead of the local bus (Java
EventEmitter.send declarative hook) — user code cannot tell a remote
route from a local one. The x-event-api envelope header marks an
event that already crossed the wire, so it is never re-forwarded.
Sourcepub fn send_later(&self, event: EventEnvelope, delay: Duration) -> String
pub fn send_later(&self, event: EventEnvelope, delay: Duration) -> String
Schedule a future one-time delivery (Java po.sendLater(event, time)):
the event is sent after delay; the returned timer id cancels it via
cancel_future_event. The timer rides an
abortable tokio task (map-don’t-mirror; increment E-3 — built for the
event-script flow TTL watcher).
Sourcepub fn cancel_future_event(&self, timer_id: &str) -> bool
pub fn cancel_future_event(&self, timer_id: &str) -> bool
Cancel a scheduled delivery (Java po.cancelFutureEvent(id)).
Returns whether the timer was still pending.
Sourcepub fn my_correlation_id(&self) -> Option<String>
pub fn my_correlation_id(&self) -> Option<String>
The business correlation-id of the current traced request
(Java getMyCorrelationId). None outside a trace or when the
incoming event carried none.
Sourcepub fn my_trace_id(&self) -> Option<String>
pub fn my_trace_id(&self) -> Option<String>
The current trace id (Java getTraceId on the trace-aware PostOffice).
Sourcepub fn my_trace_path(&self) -> Option<String>
pub fn my_trace_path(&self) -> Option<String>
The current trace path.
Sourcepub fn my_span_id(&self) -> Option<String>
pub fn my_span_id(&self) -> Option<String>
The current hop’s own span id (Java getTrace().spanId) — what a
function stamps as the parent of the NEXT hop when it carries the
trace context across a non-event boundary (e.g. a Kafka record’s
W3C traceparent header). None outside a trace or in a
zero-traced hop, which owns no span.
Sourcepub fn annotate_trace(&self, key: &str, value: impl Serialize) -> &Self
pub fn annotate_trace(&self, key: &str, value: impl Serialize) -> &Self
Attach business context to the distributed-trace dataset that flows
to the telemetry sink (Java annotateTrace). Silent no-op outside a
trace.
Sourcepub fn update_context(
&self,
key: &str,
value: impl Serialize,
) -> Result<(), AppError>
pub fn update_context( &self, key: &str, value: impl Serialize, ) -> Result<(), AppError>
Attach business context to the application log stream only (Java
updateContext) — appears in the context block of every subsequent
structured log line of this request. A null value removes the key.
The reserved keys — the trace-context names in both spellings (cid,
traceId / trace_id, tracePath / trace_path, spanId / span_id,
parentSpanId / parent_span_id, service, utc, timestamp) — are
rejected with a 400; outside a trace the call is a silent no-op. A key
the template also emits never shadows the template: the template wins.
Sourcepub async fn request(
&self,
event: EventEnvelope,
timeout: Duration,
) -> Result<EventEnvelope, AppError>
pub async fn request( &self, event: EventEnvelope, timeout: Duration, ) -> Result<EventEnvelope, AppError>
RPC (Java po.request(event, timeout)): deliver the event and await the
reply through a temporary inbox. Timeout → status 408.
A route declared in yaml.event.over.http forwards transparently as an
Event-over-HTTP RPC and returns the peer’s reply (Java
EventEmitter.asyncRequest/eRequest declarative hook); the
x-event-api recursion guard applies as in send.