Scheduling API

A primary function of Spacetime’s southbound interface is to allow the controller to maintain a forward-looking schedule of configuration changes on each agent.

This includes scheduling forwarding-rule configuration and packet-processing behavior, as well as beam pointing, channel selection, and beam-hopping configuration.

At a high level, an agent’s schedule may be thought of as a time-series of configuration changes.

The agent is responsible for ensuring that all configuration changes scheduled for instants in the past have been applied in chronological order. As time advances past a configuration change’s scheduled time, the agent applies that change.

Spacetime may modify an agent’s schedule for two broad reasons:

  1. To extend the schedule into the future as time passes.

    A network operator may, for example, wish to ensure that each agent always has a schedule that extends at least X minutes into the future. As time passes and the end of the schedule nears, Spacetime must extend the agent’s schedule beyond the X minute horizon.

  2. To revise a part of the schedule.

    Spacetime may choose to revise segments of an agent’s schedule in response to receiving information that was not available when the schedule was first generated (a new weather forecast, for example, or a notification of a hardware failure).

The scheduling service exposes two methods:

  • Reset: this method notifies Spacetime that an agent’s schedule has been reset. The agent must call this upon initialization and after any event that erases the agent’s schedule (data loss on the agent, for example).

  • ReceiveRequests: this method establishes a bidirectional stream through which Spacetime may send scheduling requests to an agent, and the agent may respond.

Diagram of the Scheduling Service

Reset Method

Diagram of Reset method

To start receiving updates to its schedule, an agent should first call Reset.

ReceiveRequests Method

Diagram of ReceiveRequests method

After the Reset method has been invoked, the agent may call ReceiveRequests with a ReceiveRequestsMessageToController.Hello message:

"hello": {
  "agent_id": "1c1bb454-beea-47bd-841e-0a7eb234b34a"
}

The agent_id should be populated with the ID of the EK_SDN_AGENT resource in the Model API that represents the agent.

Once the Bidirectional channel has been established, Spacetime will send the agent ReceiveRequestsMessageFromController messages, each of which will contain one of the following request messages:

CreateEntryRequest

A CreateEntryRequest message requests that the agent create a new entry in its schedule. The request will include the schedule entry contents, made up of a scheduled time and a configuration change to initiate at that time.

The scheduled configuration change may be one of the following:

UpdateBeam, DeleteBeam

Expand Diagram

Diagram of UpdateBeam and DeleteBeam

SetRoute, DeleteRoute

Diagram of SetRoute and DeleteRoute

SetSrPolicy, DeleteSrPolicy

Diagram of SetSrPolicy and DeleteSrPolicy

DeleteEntryRequest

A DeleteEntryRequest requests that an agent delete a particular entry from its schedule.

⚠️

A CreateEntryRequest or DeleteEntryRequest may create or delete a schedule entry whose scheduled time is in the past.

Upon receiving a change to a schedule entry scheduled in the past, the agent should update its configuration to reflect what it would have been had the request been received in time. This may be thought of as “replaying” the past schedule entries (with the referenced entry created or deleted as requested) to determine what the current configuration should be.

FinalizeRequest

The other message type an agent may receive in response to a ReceiveRequests call is a FinalizeRequest. This represents a promise from Spacetime that it will not create or delete any schedule entries scheduled for before a given instant in time. In other words, Spacetime is “finalizing” the schedule “up to” a specified instant in time.

While an agent is not strictly required to take any action in response to such a request, an agent may choose to use the request to trigger garbage collection of old schedule entries that will no longer be referred to or need to be replayed.

Other concepts

Sequence numbers

The scheduling service is designed to operate over channels that may re-order messages.

Because some scheduling operations are sensitive to the order in which they are applied (a “create” operation followed by a “delete” operation may leave the schedule in a different state than if the operations were applied in the reverse order), each CreateEntryRequest, DeleteEntryRequest and FinalizeRequest is annotated with a sequence number (abbreviated seqno).

A sequence number identifies the message’s place in the sequence of all requests that Spacetime sends an agent for a particular schedule manipulation token.

The first request will be annotated with a sequence number of 1, and each subsequent request will have a sequence number one greater than that of the previous request.

An agent should wait to execute a request until all previous requests in the sequence have been received and executed.

Schedule-manipulation tokens

An agent’s schedule may be impacted by events out of Spacetime or the agent’s control (for example, a restart of the agent may result in loss of the schedule).

In such an instance, it is important that schedule changes that Spacetime intended to be applied to the agent’s schedule before the event are not executed on the impacted schedule.

To enforce this, the scheduling service utilizes a “schedule-manipulation token".

On startup or reset, an agent generates a unique schedule-manipulation token and reports it to Spacetime in a call to Reset.

All CreateEntry, DeleteEntry, and Finalize requests intended to be applied to the schedule from then on will be annotated with that token.

Should the agent receive a request bearing a different token, the agent must drop the request and reply with a Response message indicating a FAILED_PRECONDITION.