Events Overview

info

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 publish clusters.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)