Events#

Spaces notifies frontends of

changes,
progress updates, and
personal transient events.

To receive notifications, a frontend must subscribe to the WebSocket event feed provided by Skalio ID.

Change events#

Whenever something changes within a space, the following things happen:

a change event is recorded, containing information about the actual change,
the event sequence number of the space is increased,
an event notification is triggered for all collaborators of the space.

A client can fetch events for a space and apply the changes they describe to update locally cached information about a space. This keeps the space in sync.

Change events are stored in the database or memory-cache of the spaces application where they are kept for some time. Old events will get purged at regular intervals. No guarantee is given for how long old events are kept. When a request for events cannot be satisfied, because they had been purged previously, the client must fetch the complete space details instead, replacing the locally cached space details.

Schema#

The change event consists of the following fields:

type (String, required): See Event type
sequence (Number, required): Newer events have higher sequence numbers; sequence numbers are not necessarily contiguous
principalUid (String, optional, nullable): If the event was triggered by a person, it contains the person's UID; possibly null
payload (JSON string, optional, nullable): describes the actual change

An example:

    {
      "type": "SPACE_UPDATED",
      "sequence": 8,
      "principalUid": "jiueby0_jjdvae.b",
      "payload": {
        "uid": "hq-.k94hugbsxnf9",
        "name": "Updated name",
        "description": "Updated description at 2020-05-25T13:09:39.625Z",
        "orgUid": "n_gwumunrj77j-r0"
      }
    }

The payload describes the new state of an entity. It may be null, when there is no benefit in transporting it or when it is particularly large. Avatar pictures for example are not delivered in the payload, but must be fetched manually.

The payload may be different based on the privileges of the principal requesting the change event. Administrator privileges typically include additional information compared to read privilege. Note that the privilege evaluation occurs at the time of the request, not when the event is recorded. In other words, fetching the same list twice but changing privileges in between can result in different output.

Event type#

The following event types exist:

Type	Description	Payload contents
FILE_CREATED	A new file or directory has been created.	See File metadata
FILE_UPDATED	A file or directory has been updated (metadata or payload).	See File metadata
FILE_IN_TRASH	A file or directory has been moved to the trash.	See File metadata
FILE_RESTORED	A file or directory has been recovered from trash.	See File metadata
FILE_DELETED	A file or directory in trash has been deleted permanently.	`uid` of the file
TRASH_PURGED	All files in the trash have been deleted permanently.	none
INVITATION_CREATED	An invitation for a new collaborator has been issued.	See Invitation
INVITATION_CANCELLED	An invitation for a new collaborator has been cancelled or has expired.	See Invitation
INVITATION_ACCEPTED_BY	An invitation was accepted by a person.	See Accepted Invitation
PENDING_COLLABORATOR_CREATED	A new, pending collaborator has been created.	See Collaborator
COLLABORATOR_CREATED	A collaborator has been created - from pending state or from an invitation.	See Collaborator
COLLABORATOR_UPDATED	A collaborator has been updated.	See Collaborator
COLLABORATOR_REMOVED	A collaborator has been removed.	See Collaborator
SPACE_CREATED	A new space has been created.	See Space metadata
SPACE_UPDATED	The details of the space have been updated.	See Space metadata
SPACE_AVATAR_UPDATED	The avatar of the space has been updated.	none
SPACE_DELETED	The space has been deleted.	none

Special cases#

The event SPACE_DELETED cannot actually be fetched from the list of change events, since the space has already been deleted. Clients must interpret the situation accordingly.

When a collaborator is removed from a space, he is notified of the event. However, since his access privileges to the space have already been revoked, the event COLLABORATOR_REMOVED cannot actually be fetched by him. Clients must interpret the situation accordingly.

Space metadata#

The payload consist of:

uid of the space
name and description
orgUid, UID of the organization that owns the space

Invitation#

The payload consist of:

uid of the invitation
privilege
issuedAt and expiresAt, timestamps
personalNote, optional text for the invitee
notificationAddress, optional address where the invitation was sent
publicUrl, URL points to the frontend for human readable presentation of the invitation

The following fields are only visible to principals with admin privilege on the space:

adminReference, optional text field set by an admin

Collaborator#

The payload consists of:

personUid, UID of the person associated with the collaborator
privilege
createdAt, timestamp
pending, boolean: shows if collaborator assignment has been accepted

The following fields are only visible to principals with admin privilege on the space:

adminReference, optional text field set by an admin

Accepted Invitation#

The payload consists of:

invitation, serialized Invitation
collaborator, serialized Collaborator

File metadata#

The payload consists of:

uid of the file
path
size in Bytes
intendedSize in Bytes, as set by uploader, null if not set
mimeType
createdAt, accessedAt, modifiedAt, timestamps set by the client
deletedAt, timestamp of deletion, null if not in trash
blurHash, etag
aspectRatio as a decimal number

Event sequence#

The sequence number is a strictly increasing number greater than 1. It represents the "version number of the truth" of the space and is stored with it. The sequence number of subsequence events will always be higher, but no guarantee is given on the value of the increment.

A client should always store the latest processed event sequence number with the space. When fetching the complete details of the space, the sequence number of that point in time is included in the response.

When replaying change events, a client should observe the order of changes.

Event notifications#

When an change event occurs, the spaces backend publishes event notifications on the message broker for every collaborator of the space. Other applications, such as Skalio ID, subscribe to these messages and may notify the person according to their availability and configuration. See Skalio ID for details.

Notifications can lead to different actions, such as waking up a client application to fetch changes, or trigger an email.

Clients are encouraged to delay the reaction to a notification for short period of time to potentially collect multiple change events in one single request.

Progress events#

While data is uploaded into a space, the server will publish events describing the upload progress at regular intervals. These progress events are transient and will not be persisted, as opposed to change events.

Typically, progress events get sent every second while the upload is ongoing. The interval is fixed and not related to the upload rate.

Schema#

The events are issued over the WebSocket event-feed as a JSON-encoded SignalingEvent with type SPACE_PROGRESS_ACTIVITY. Example:

SignalingEvent{
  "uid" : "dn29szxa2_cp5ngf",
  "type" : "SPACE_PROGRESS_ACTIVITY",
  "data" : {
    "type" : "upload",
    "spaceUid" : "wtg_67.ld.vk4u.8",
    "objectUid" : "my__m9.nq0na9lok",
    "principalUid" : "dn29szxa2_cp5ngf",
    "size" : 17566678,
    "byteCount" : 17566678,
    "complete" : true
  },
  "timestamp" : "2021-12-08T10:13:44.290139Z"
}

uid (String, required): UID of the event recipient.
type (Enum[String], required): SignalingEvent type.
data (String, required): Event payload
- type (Enum[String], required): Type of activity that causes the progress updates.
  - upload: The object is being written to.
- spaceUid (String, required): UID of the affected space.
- objectUid (String, required): UID of the affected object.
- principalUid (String, optional, nullable): UID of the person that causes the events.
- size (number, required): Intended size of the request; 0 if information cannot be obtained.
- byteCount (number, required): Current state of progress; 0 if information cannot be obtained.
- complete (boolean, required): true while the request modifying the object is alive; false after the end.

Notes:

principalUid may be null, if the progress activity is caused by backend services themselves.
size and byteCount are delivered based on available information as reported by clients. No guarantee is made about size >= byteCount or such. Values default to 0; take this into consideration and avoid division-by-zero errors.
complete = true indicates that the request processing the object has ended. This does not necessarily need to coincide with size == byteCount! Partial uploads can upload only parts of a file, with byteCount never reaching the intended size; still completed = true at the end of the request.
- This may be used by frontend to detect incomplete uploads.
- Once complete = true, expect no further updates regarding this object/this operation.

Personal events#

Some events are only sent to specific persons. They help with flow control or notify the person of a certain situation. These personal events are transient and will not be persisted, as opposed to change events.

The event stream delivers these events to all subscriptions of the targeted person simultaneously. It is the responsibility of the frontend to handle the same events arriving at multiple clients, and to coordinate actions or responses appropriately.

Offline clients will not be able to replay such events. It is the responsibility of the clients to fetch the latest version of the truth when the client becomes online from either a fresh start or after a loss of connection.

Aborted upload#

When the upload of a space-file is interrupted before reaching the end of file, an event is issued to the principal who performed the upload. Clients can then handle the situation based on the intention of the principal.

Interrupting an upload does not automatically remove the partial upload. Instead a client can request information about the uploaded file and attempt to resume uploading to it, or remove the partial upload by deleting it.

The event is sent as a JSON-encoded SignalingEvent with type SPACE_UPLOAD_ABORTED. Example:

SignalingEvent{
  "uid" : "dn29szxa2_cp5ngf",
  "type" : "SPACE_UPLOAD_ABORTED",
  "data" : {
    "type" : "upload",
    "spaceUid" : "wtg_67.ld.vk4u.8",
    "objectUid" : "my__m9.nq0na9lok",
  },
  "timestamp" : "2021-12-08T10:13:44.290139Z"
}

uid (String, required): UID of the event recipient. This is the principal who performed the upload.
type (Enum[String], required): SignalingEvent type.
data (String, required): Event payload
- type (Enum[String], required): Type of activity that causes the aborted update.
  - upload: The object is being written to.
- spaceUid (String, required): UID of the space that contains the aborted object.
- objectUid (String, required): UID of the aborted object.

Capacity changes#

When the allocated storage limit or used storage volume of an organization changes, all collaborators of the organization will receive this event. Clients can use this event to show users the currently used storage, and how much of their organization's allocated storage they have left.

The event is sent as a JSON-encoded SignalingEvent with type SPACE_CAPACITY_UPDATED. Example:

SignalingEvent{
  "uid" : "dn29szxa2_cp5ngf",
  "type" : "SPACE_CAPACITY_UPDATED",
  "data" : {
    "orgUid" : "wtg_67.ld.vk4u.8",
    "allocatedStorage" : 84295010,
    "usedStorage" : 84295010
  },
  "timestamp" : "2021-12-08T10:13:44.290139Z"
}

uid (String, required): UID of the event recipient. This is a collaborator in one of the organization's spaces.
type (Enum[String], required): SignalingEvent type.
data (String, required): Event payload
- orgUid (String, required): UID of the organization.
- allocatedStorage (number, required): The total allocated storage to this organization, in Bytes.
- usedStorage (number, required): The currently used storage volume of this organization, in Bytes.