Subscriptions & Events¶
How a standing interest in what is happening where becomes a real-time stream of events delivered to your application. This page is the conceptual model; for hands-on use see Application SDK: managing subscriptions and API: subscriptions. Subscribing is accepted at once and set up in the background: the platform tells you what it matched — the coverage report — and keeps re-matching every hour as sensors and lenses change.
A subscription is what + where + how¶
A subscription is a standing, server-side request for events. You define it with three parts:
| Part | Question it answers | What it is |
|---|---|---|
| Event types | What do you care about? | One or more event types — the kinds of observation you want |
| Geographic regions | Where do you care about it? | One or more region codes, or * for everywhere you can see |
| Lens | How should sensor data become events? | A lens — one of your organization's, or a public one — referenced by its alias |
You provide these once. The platform accepts the subscription immediately, provisions it in the background — matching sensors, running the processing the lens implies, and wiring their events to your queue — and re-checks that match every hour until you delete the subscription. The subscription is owned by the app client that created it and lives independently of any running process.
What (event types)¶
An organization defines its event vocabulary as tags — named, hierarchical entries describing kinds of events. An event type is a tag used as a subscription filter. When you subscribe you list the event types you want; the platform exposes which ones are valid. Only events of those types are delivered.
An event type the platform does not know is refused before anything is created, and the refusal names it. Every type you ask for is kept — none is silently dropped — and the coverage report says, type by type, whether something is currently producing it for you.
Where (geographic regions)¶
A geographic region is a short code for an area on the map. The codes are hierarchical: shorter codes cover wider areas, longer codes zoom in — from a continent, down through a city, to a single block. A code is between one and nine characters long; anything finer is refused. The single value *, given on its own, means everywhere you can see.
A subscription lists one or more regions — or * alone — and matches any sensor whose area of view overlaps any of them. The area of view is the patch of ground the sensor observes, not the point it is mounted on: a camera on a corner that watches a street is matched by a request for that street even if the camera itself stands outside it. A short code casts a wide net and a longer one narrows the focus.
Eligible sensors are your organization's own sensors plus any organization's public sensors, while they are active and not decommissioned. A public sensor from another organization contributes its events to your subscription, but its connection details and metadata are never shown to you.
Some bounds apply, all checked before anything is created:
- A cell nested inside a coarser cell you also asked for collapses into the coarser one.
- At most 64 cells per subscription, after collapsing.
- A request that would match more than 200 sensors is refused — ask for a smaller area.
- At most 100 live subscriptions per organization.
Regions select sensors, not events
Regions decide which sensors serve you. Once a sensor is matched, every event its processors publish for your event types is delivered. The position stamped on an event is the one the template chose to record, and the platform does not filter events by it.
How (lens)¶
Sensors emit raw data; processing turns that raw data into meaningful events. A lens is a named, aliased group of that processing, curated by an organization manager in the Portal. The lens you choose decides how raw sensor data becomes events — and therefore what your events look like. Two lenses over the same sensors can produce different event streams.
A lens is either private — usable only by the organization that owns it — or public — usable by any organization. You reference a lens by its alias; it may be one of your organization's own lenses or any public lens. An alias that does not exist and another organization's private lens are refused with the same answer — the platform does not reveal which.
Each subscription uses exactly one lens. A lens groups processor templates, which organizations publish as public or private; a public lens can contain only public templates. Only templates with an approved, active version take part in matching. Several templates in a lens may produce the same event types: for each sensor type the platform picks the smallest set of templates that covers your request, and each requested event type reaches you from exactly one processor per sensor. You focus on the events you want and leave the choice of processing to the lens.
A lens can be edited or deleted at any time; the hourly re-check adapts every subscription using it. If another organization's lens you rely on is made private, your subscription stays active with every event type marked uncovered (LENS_NOT_ACCESSIBLE) and recovers on its own once the lens is public again. If the lens is deleted, the subscription stays active with nothing covered; a subscription cannot be pointed at a different lens, so create a new one.
From subscription to delivered stream¶
sequenceDiagram
autonumber
participant App as Your application
participant API as Dory API
participant Q as Your delivery queue
participant W as Worker
participant O as Orchestrator
App->>API: subscribe (event types · regions · lens alias)
API->>API: check the types, the lens and the region bounds
API->>Q: create the queue
API->>W: provision ticket (worked one at a time, in order)
API-->>App: accepted · subscription id · status pending
App->>Q: start consuming (nothing arrives yet)
W->>W: match sensors by area of view · choose templates per sensor
W->>O: reuse a live processor or request a new one (one per sensor × template)
O->>O: start the container on its next poll
W->>Q: bind each processor's events of your types to the queue
W->>Q: control message ready (coverage report)
W->>W: status pending to active
O->>Q: the processors publish events
Q-->>App: events · control messages
- You declare the subscription — event types, regions, and lens alias — through the Application SDK or the API.
- The platform checks the event types, the lens and the region bounds. A refusal here creates nothing — see Refusals.
- It creates your dedicated delivery queue and answers accepted with the subscription id and status
pending. You can start consuming the queue immediately. - In the background, a worker finds the sensors — yours and public ones — whose area of view overlaps your regions, and chooses the lens templates that cover your event types for each sensor.
- For every sensor × template pair it reuses a processor that is already running, or starts a new one.
- It binds your queue to each processor's events of your types, posts a
readycontrol message carrying the coverage report, and the status becomesactive. - Events flow into your queue, and your application consumes them.
Nothing matched is not an error
A subscription with no matching sensors, or whose lens produces none of your event types, is still created and becomes active. Its coverage report marks every event type uncovered, with the reason. The first hourly re-check after a matching sensor or template appears starts delivery, and tells you with an updated message.
Processors: one per sensor and template, shared¶
A processor is one running container for one sensor and one template. Processors are shared: two subscriptions — even from different organizations — that need the same sensor × template pair use the same processor. When your subscription is provisioned, a pair that is already running is reused; otherwise a new processor is requested and the orchestrator starts it on its next poll. The coverage report counts processors reused and started separately.
flowchart LR
SA["Sensor A"] --> PA1["Processor A × template 1"]
SB["Sensor B"] --> PB1["Processor B × template 1"]
SB --> PB2["Processor B × template 2"]
PA1 -->|"person"| Q1[("Subscription 1 queue<br/>person · A and B in view")]
PB1 -->|"person"| Q1
PB1 -->|"person"| Q2[("Subscription 2 queue<br/>person + vehicle · B in view")]
PB2 -->|"vehicle"| Q2
Your delivery queue is bound to each processor serving you, one binding per requested event type, so it receives only your requested types from those processors — nothing from processors serving other subscriptions alone, and nothing of a type you did not ask for. When the last subscription using a processor is released, the processor is stopped.
The coverage report¶
The coverage report is the platform's answer to "what did you match for me?". It has five fields:
| Field | What it says |
|---|---|
event_types |
For each event type you requested: covered (true or false) and, when not covered, a reason |
sensors_matched |
How many eligible sensors have an area of view overlapping your regions |
sensors_served |
How many of those have at least one processor producing your event types |
processors_started |
How many processors this run started for you |
processors_reused |
How many already-running processors this run attached you to |
The reasons an event type can be uncovered:
| Reason | In plain words |
|---|---|
LENS_NOT_ACCESSIBLE |
The lens no longer exists, or is now private to another organization; nothing is matched while that lasts |
NO_SENSORS_IN_REGION |
No eligible sensor's area of view overlaps your regions |
NO_TEMPLATE_EMITS_IT |
No template in the lens with an approved, active version produces this event type |
NO_COMPATIBLE_SENSOR |
A template does produce it, but none of the matched sensors is of a type that template supports |
The report never contains sensor ids, sensor names, coordinates or processor ids — only counts and per-type coverage. It arrives in the ready control message, in every updated message, when you read the subscription by id, and as the return value of the SDK's wait_until_ready.
Control messages¶
Besides events, the platform drops three kinds of control message into your delivery queue:
| Message | When | What it carries |
|---|---|---|
ready |
Provisioning finished | The coverage report |
updated |
An hourly re-check changed your coverage | The new coverage report |
error |
The worker gave up setting the subscription up (BROKER_REFUSED or PROVISIONING_FAILED) |
The error code and a plain sentence saying what to do |
They travel in the same queue as your events. The Application SDK handles them itself — they never reach your event callback — and uses them to answer wait_until_ready and to keep its local view of the subscription current. Events can arrive before ready: a processor reused from another subscription may already be publishing when your binding is made. An application on an SDK older than 1.2.0 keeps receiving events, but sees each control message as one callback call carrying a subscription_id and status instead of an event payload.
Receiving events¶
Each subscription has its own delivery queue, and your application reads events from it — the Application SDK consumes the queue and hands each event to your code. An event arrives as a JSON object — conceptually a versioned envelope wrapping a payload. The shape of the fields depends on the lens and event type that produced it, so two event types can look quite different.
The queue is durable, holds a message for up to one hour, and keeps at most 10,000 messages waiting — so consume promptly rather than letting events pile up while your application is away.
Delivery is at-least-once: the same event may occasionally arrive more than once, so design your handler to tolerate duplicates — for example by keying on the event's message id and ignoring ones you've already processed. The Application SDK section shows how to connect to a queue and handle events in code.
Status and lifecycle¶
stateDiagram-v2
[*] --> pending: subscribe accepted
[*] --> error: created before the current delivery system · LEGACY_RESUBSCRIBE
pending --> active: provisioned · ready message (coverage report)
pending --> error: setting up failed · BROKER_REFUSED, PROVISIONING_FAILED or QUEUE_ORPHANED
active --> active: hourly re-check · updated message only if coverage changed
pending --> deleting: delete
active --> deleting: delete
error --> deleting: delete
deleting --> [*]: queue removed at once · processors released shortly after
| Status | What it means | What to do |
|---|---|---|
pending |
Accepted; the worker has not finished setting it up. Your queue already exists. | Consume the queue, or wait for ready |
active |
Provisioned. The coverage report may still be empty — see Nothing matched is not an error above. | Read the coverage report to see what is serving you |
deleting |
Delete accepted; the queue is already gone and the processors are being released. | Nothing — it disappears from your lists |
error |
The subscription could not be set up, or predates the current delivery system. It carries an error code. | Delete it and subscribe again |
An active subscription never moves to error: a re-check that fails leaves it serving you as before and is simply tried again. Apart from subscriptions created before the current delivery system, only one that has not yet become active can end in error.
A subscription lives server-side until you delete it — it is not tied to your process or session. Until you delete it you can read it by id: its status, its coverage report, its error code when it is in error, and when it became active. The app client that created it can list the subscriptions it owns — pending, active and in error — and delete them by id, including ones created in an earlier session — see Application SDK: managing subscriptions. In the Portal, an app client's details dialog lists that credential's subscriptions with their status: a subscription in error shows the plain explanation for its code, an active one lists each uncovered event type with its reason, and a member with the delete permission can delete them.
When a subscription is in error¶
A subscription in error carries one of four codes. You only ever see the code and a plain sentence keyed on it; the technical detail behind it stays with the platform, so quote the subscription id if you contact support. Whatever the code, the remedy starts the same way: delete the subscription and subscribe again.
| Code | What happened | What to do |
|---|---|---|
BROKER_REFUSED |
The message broker refused a request while the subscription was being set up; retrying on its own cannot fix it | Delete it and subscribe again; if it keeps failing, contact support with the subscription id |
PROVISIONING_FAILED |
Setting up kept failing on temporary problems and ran out of attempts after five runs | Delete it and subscribe again; if it keeps failing, contact support with the subscription id |
QUEUE_ORPHANED |
The delivery queue could not be created, and the half-made queue could not be cleaned up either (the subscribe call itself answered BROKER_UNAVAILABLE) |
Delete it — that also cleans up the queue — and subscribe again |
LEGACY_RESUBSCRIBE |
The subscription was created before the current delivery system and is never set up again | Delete it and subscribe again |
BROKER_REFUSED and PROVISIONING_FAILED are also announced by an error control message in the delivery queue. The Application SDK raises them from wait_until_ready and maps every code to the same sentence, and the Portal shows the same explanation in the app client's details dialog.
The hourly re-check¶
Once a subscription is active, the platform re-runs the match every hour from what you asked for — the same rules as the first time — and compares the result with the processors serving you now.
flowchart TB
T["Every hour, for each active subscription"] --> M["Match again from your event types, regions and lens<br/>(the same rules as the first time)"]
M --> D{"Compare with the processors<br/>serving you now"}
D -->|"sensor installed, published or moved into view ·<br/>template attached · processor failed or stopped"| ADD["Add the pair:<br/>reuse or start a processor · bind your queue"]
D -->|"sensor moved away, unpublished or decommissioned ·<br/>template detached or revoked · lens made private or deleted"| DROP["Drop the pair:<br/>unbind · stop the processor if nobody else uses it"]
D -->|"queue or binding missing on the broker"| FIX["Restore it from the platform's own record"]
D -->|"nothing changed"| NOOP["Nothing to do"]
ADD --> R["Coverage report recomputed"]
DROP --> R
FIX --> R
R -->|"changed"| U["control message updated"]
R -->|"unchanged"| S["silent"]
What the re-check catches:
- A sensor is installed, published, unpublished, moved or decommissioned — the affected pairs are added or dropped.
- The lens is made private or deleted — every event type becomes uncovered with
LENS_NOT_ACCESSIBLEand the subscription stays active. A lens made public again is picked up by the next re-check; a deleted one never comes back. - A template is attached to or detached from the lens, or its version is revoked — the pair is added or dropped. Revocation also stops the running processor within the orchestrator's next poll; the re-check then re-adds the pair on another live version of the template, or drops it.
- A processor failed or was stopped — the pair is re-added on a live processor.
- The broker lost your queue or a binding (for example, after a restore from backup) — both are put back from the platform's own record of what should exist.
- A provisioning or release that never ran — a subscription still
pending, or a delete not yet released, more than ten minutes after it was requested is picked up again by the next hourly run.
You are told with an updated message only when your coverage actually changed; a silent hour means nothing about your subscription moved. A re-check that could not finish is tried again the next hour; it does not take an active subscription out of service.
Unsubscribing¶
Deleting a subscription answers accepted with status deleting. Your delivery queue is removed inside the request, so delivery stops at once and your consumer is cancelled. The processors are released shortly afterwards in the background; a processor still used by another subscription keeps running, and one nobody uses any more is stopped. A subscription in any status — pending, active or error — can be deleted this way.
Who may delete a subscription:
- the app client credential that created it;
- an organization member with the delete permission, from the Portal.
Another credential in the same organization is refused — a subscription is its creator's. A subscription that is already gone can be treated as deleted: the SDK does exactly that and forgets it, but keeps its record of one it was refused.
Refusals¶
A subscribe request that cannot be honoured is refused, and no subscription is set up. Each refusal carries a code, which the Application SDK raises as a typed error:
| Code | Why |
|---|---|
INVALID_REQUEST |
The request is malformed — a missing or empty field, or the wrong kind of value |
UNKNOWN_EVENT_TYPE |
An event type is not in the vocabulary; the message names it |
LENS_NOT_ACCESSIBLE |
The alias does not exist, or names another organization's private lens — the same answer for both |
INVALID_REGION |
A region code is not a valid geohash, or * was mixed with other cells |
REGION_TOO_FINE |
A region code is longer than nine characters |
TOO_MANY_CELLS |
More than 64 cells after nested ones collapse |
TOO_MANY_SENSORS |
The regions would match more than 200 sensors — ask for a smaller area |
QUOTA_EXCEEDED |
Your organization already has 100 live subscriptions |
BROKER_UNAVAILABLE |
The message broker did not accept the delivery queue. Normally nothing is left behind, so retry; in the rare case the half-made queue could not be cleaned up, a subscription in error with the code QUEUE_ORPHANED remains — delete it |
All but the last are decided before anything is created.