Events Overview
Nile's Event APIs and SDKs are in active development and not everything described below is fully implemented in every SDK yet. The APIs and SDKs themselves are likely to evolve.
Treat this documentation as an invitation to explore and collaborate with us. We are actively seeking to learn more about control plane architectures, so we can make our APIs and SDKs more useful in various scenarios. Contact gwen@thenile.dev if you want to help. Even an hour conversation will be useful.
Nile Platform publishes system events
when their APIs are called and trigger transitions in the entity's lifecycle.
All entities, built-in or custom, publish the following events:
Event name | When is it published |
---|---|
entity.created | published immediately after an entity instance is created |
entity.updated | published after any modification to the entity data |
entity.deleted | published when an entity instance is deleted |
Examples:
- After a user changes their password, event
users.updated
is published. - If you have a custom entity called
clusters
, after a user deletes an instance of a cluster, Nile will publishclusters.deleted
event.
Built-in entities may have additional events, those are documented with the entity.
Examples:
- When a user logs in,
users.logged_in
event is published. - When a user accepts an invite to an organization,
invites.accepted
event is published.
Event APIs
Events are always published by Nile. Clients subscribe to events via Nile SDKs and register event handlers. The SDK is responsible for triggering the handlers when appropriate events are received.
Subscribing to all clusters.created
events:
nile.onEvent('clusters.created').handle(cluster_create_handler)
When called, the handler receives a payload with the entity type, the entity instance ID and the after image of the instance.
For example, when a cluster is renamed, the payload is:
{
"id": 35,
"type": "clusters",
"properties": {
"cluster_name": "NewClusterName",
"region": "us-east-2"
}
}
Guarantees
This is in active development, but we are aiming at the following:
- At least once processing semantics. For each event, registered handlers will be called at least once.
- Events for each entity instance will be processed in the same order in which they were published.
Usage in control plane agent
We designed Nile events toward the goal of a control plane agent, running near or in the data plane application, consuming events from the control plane and taking action in the data plane based on these events.
For example, when a user uses the control plane web application to create a new cluster, Nile will publish cluster.created
event. We expect the agent to register a handler for those events that will take appropriate action in the data plane to create the action.
We recommend that each handler, as a last step in its processing, the handler will use Nile's CRUD APIs to update the control plane in the results of the action. Especially the success / failure of the action and any relevant error information. This will give the control plane users visibility into the state of the data plane.
For example:
def create_cluster_handler(event):
try:
# Do something to create a cluster
...
# Update Nile
event['properties']['status'] = 'success'
nile.update_instance(event['type'], event['id'], event)
except:
# Update Nile
event['properties']['status'] = 'failed'
nile.update_instance(event['type'], event['id'], event)