Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Concepts: Events, Streams and Rights
The data atom in Evernest is the event. An event can be any kind of data, but since these pieces of data are ordered chronologically (in the order in which they have been inserted), it is more convenient to think of them as events.
We use the term event because a common use case of Evernest is log monitoring, and log entries are time-ordered.
For instance, an event can be an access to a given resource on a web server, or an action in a content manager (adding, removing or editing an object). It can also be a commit in a project.
Technically, events are just strings that you can format as you wish.
Events are pushed into some big timelines called streams. A stream is nothing more than a collection of events and contains generally the succession of events generated by a given source.
For instance, a stream can gather all events related to a development project (commits, merges, comments, issues, etc). Or it can be made of your system logs.
Events in a stream are designated by their ID. When you push a new event, Evernest returns you its ID.
Events from a stream can be accessed in two ways:
- Get a random event
- Get a slice of the timeline, i.e. all the events between two IDs
A source is a program that pushes events though the Evernest API.
A stream can be filled by one or more sources. And a single source can push events to many streams. It is up to you to organize your streams as you wish.
For instance, let's imagine you have a stream for your system errors and another one to log all information about, say, your mailing server. You may want your mailing error manager to log errors in both streams. Moreover this will not be the only program to write to the system errors stream.
Actually, sources are an abstraction of programs. It adds a level of indirection since it is just represented as an API key, so that many programs can act as the same source or a single program can have several modules accessing the Evernest API with different rights. This organisation allows you to deal with complex setups and add sanity mechanisms (different parts of the same program will act as different sources with different rights).
Another benefit of this abstraction is that whenever a source gets corrupted (i.e. the API key has been compromised), you can invalidate only the key associated with that program, without having to add a new key in each project that you've connected to Evernest. There is fundamentally no problem in using your Evernest account to manage many independant projects.
In order to organize your streams and the sources that access it, Evernest embeds a basic rights system.
A right is the set of actions a given source has on a given stream. The source can:
- Do nothing (
- Read from the stream (
- Write to the stream (
- Read from and write to the stream (
- Read, write and edit the related table rights (
For instance, the previous mailing application would be able to send errors to the system errors stream but should not be able to read it because it contains information about the whole system.
Admin rights can be ignored in most basic projects in which right tables are static, i.e. you manually provide sources their rights and it will not be changed by the programs themselves (although you may want to change your workflow at some point).
But if you want to build a program that helps you managing some streams and sources, you may provide it the
Admin rights. Note that these rights allow you to get a list of all available sources.
Your base source (i.e. your first API key) is a special key that always keeps the
Admin rights on all your streams. If this key was to be corrupted, you cannot simply destroy the key but need to regenerate a new one in order to replace it.
Rights are a very powerfull way to keep control on which application does what with which stream, but it becomes tricky when you want to use it in order to work with other people and allow them some actions on some streams.
You could create new sources and give them to your collaborators, but it won't be possible for them to organize themselves with differents sources and have a flexible workflow in turn. Sources should remain what they are, namely programs. It should not be a hacky way to give access to some part of your streams or you'll get into trouble sooner or later.
So we developped another right system, defining relations between people. Right names are the same:
But these are the rights a user has on a stream, and not a source. Basically, it is a right for a user to create sources writing into or reading from the stream. The user you give the right to can then organise his API keys as he wants.
Admin right allow the user to edit user rights. Many users can have it, so that you can easily share streams with other users.