Output & Events¶
A processor produces results by publishing events. You make one call per event. The SDK turns the location you give it into the event's routing key, attaches your trace context, and sends the event to the platform's event exchange, retrying and buffering through short broker outages. The platform decides which subscribers receive it, by processor and event type.
Publishing an event¶
The one call you need is publish. You give it an event type (what kind of result this is), a location (a GeoPoint), and a payload already wrapped in the standard envelope:
from dory.geo import GeoPoint
from dory.output import MessageEnvelope
await self.publish(
"person",
GeoPoint(lat=26.3683, lng=-80.1289),
MessageEnvelope(payload={"label": "person", "confidence": 0.93}).to_dict(),
)
- Event type: use the slug of an event type your template version declares (see Sensors & Tags). Subscriptions request event types by slug, and a subscriber's queue is bound to your processor by slug, so an event published under any other name reaches no one. An empty event type raises
ValueError. - Location: the point this event is about. It must be a valid coordinate (latitude −90 to 90, longitude −180 to 180), or
publishraisesValueError. See Where the location comes from. - Payload: your data inside a
MessageEnvelope, described next.
The standard envelope¶
publish sends the payload exactly as you pass it: it does not wrap it for you. Build the envelope with MessageEnvelope, as the template scaffold and the SDK's examples do. You supply payload, and it fills in the other three fields:
{
"schema_version": "<MAJOR.MINOR>",
"message_id": "<unique id>",
"timestamp": "<ISO-8601 UTC>",
"payload": { "...": "your data" }
}
Subscribers are written against this shape. The Application SDK hands each application the parsed JSON, and applications read message_id and payload from it. A payload published without the envelope reaches them without those fields.
Build a new envelope for every event. Each one gets its own message_id, and subscribers are expected to ignore an id they have already processed.
The envelope's version follows two rules. A minor bump (for example 0.1 → 0.2) only adds optional fields. A major bump (0.x → 1.0) is a breaking change. Subscribers should match on the major version.
The event type and location are not in the envelope. They travel on the routing key.
The routing key¶
The SDK builds every event's routing key from three parts:
‹processor id›.‹event type›.‹geohash: nine characters, one per segment›
e.g. ‹processor id›.person.d.h.x.p.f.r.5.b.7
- Processor id: this running processor's identity, supplied by the platform.
- Event type: the string you passed to
publish. - Geohash: the location you passed, encoded to nine characters and spelled one character per segment.
Where the location comes from¶
The GeoPoint you pass is the only source of the location in the key. The SDK encodes it, and nothing else in the platform sets, corrects or replaces it.
- The sensor's own location is not used for you. The platform gives your container the sensor's location as a geohash in
DORY_GEOHASH, butpublishnever reads it. To stamp the sensor's position, pass it as aGeoPointyourself. - The scaffold stamps a placeholder. A freshly scaffolded template publishes one constant location (
PROCESSOR_LAT/PROCESSOR_LNG) on every event until you replace it. - Per-detection positions are your template's job. The SDK's
CameraGeolocalizerestimates a position for each detection from the sensor's calibration points inDORY_GEO_REFERENCE_POINTS, which needs at least four points with its default method. The SDK's reference camera example falls back to a fixed camera location when there are none.
See Stamping a location and What your container receives in the template developer guide.
Who receives an event¶
Subscribers are not bound to the location in your key. For each subscription your processor serves, the platform binds that subscription's queue to
with one binding per requested event type your processor serves. The binding has no region segment.
flowchart LR
P["Your processor<br/>publish('person', location, envelope)"]
X["Event exchange"]
A["Subscription A's queue<br/>bound to ‹processor id›.person.#"]
B["Subscription B's queue<br/>bound to ‹processor id›.vehicle.# only"]
P -->|"routing key<br/>‹processor id›.person.d.h.x.p.f.r.5.b.7"| X
X -->|"processor id and event type match;<br/>the geohash segments are not compared"| A
X -.->|"no person binding: not delivered"| B
The binding compares the processor id and the event type. The nine geohash segments are carried along but never compared.
- Regions select sensors, not events. When a subscription is matched, its regions pick sensors by each sensor's area of view. Once your processor is matched, every event it publishes under a bound event type is delivered to that subscription, wherever the event is stamped, even outside the subscriber's regions. See Subscriptions & Events.
- The platform does not filter by the location you stamp. A wrong stamp misplaces your events for every subscriber, and nothing corrects it. A right stamp does not narrow who receives them.
- One processor can serve many subscriptions. Each subscription has its own bindings and receives its own copy of every event that matches them.
- An event type nobody requested reaches no one. If no subscription served by your processor asked for a type, events of that type are delivered to nobody.
The platform adds and removes these bindings as subscriptions are created, deleted and re-checked. Your processor keeps publishing the same way.
Delivery¶
If a publish fails, the SDK retries it. If the broker stays unreachable, the SDK buffers the event and replays it once the connection is back, so a momentary outage doesn't silently drop results. The buffer lives in the processor's memory and is bounded. When it fills, the oldest buffered events are dropped first.
Subscribers receive events at least once, so a subscriber may occasionally see the same event more than once. Consumers are expected to de-duplicate on the envelope's message_id, which is another reason every event needs its own envelope.
Tracing travels with every event¶
When you publish, the SDK records the publish as a span in your current trace. It also puts the trace context (a W3C traceparent) into the event's message headers, for buffered events too, alongside any headers you pass. A consumer that reads that header can continue the same trace. See Observability for the full tracing story.
Platform-managed delivery¶
You never configure brokers, connection URLs, or credentials in your processor. On the platform, your processor is given a shared, platform-managed credential that can only publish. It cannot declare queues, bind or read, so a processor never consumes other processors' events.
Leave publish's exchange argument unset. Subscriptions are bound on the platform's event exchange, so an event sent to any other exchange reaches no subscriber.
Note
Event delivery is available when a processor runs on the Dory platform. During a purely local run without the platform, publish() raises a RuntimeError, because there is no broker to deliver to. The template scaffold guards its example call and logs no publisher configured; would emit … instead. See Configuration.