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 antenna targeting, 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:
-
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 out into the future. As time passes and the end of the schedule nears, the SDN controller must extend the agent’s schedule beyond the X minute horizon.
-
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 startup and after any event that resets the agent’s schedule. -
ReceiveRequests: this method establishes a bidirectional stream through which Spacetime may send scheduling requests to an agent, and the agent may respond.
Reset Method
To start receiving updates to its schedule, an agent should first call Reset.
ReceiveRequests Method
After the Reset method has been invoked, the agent can 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 network node the agent is representing: Spacetime assumes a 1:1 relationship between network nodes and agents.
Once the Bidirectional channel has been established, Spacetime will communicate to the agent using ReceiveRequestsMessageFromController messages which can include one of the following instruction:
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:
-
SetBeamorDeleteBeam, describing a change to a modem’s configuration. -
SetBeamHoppingPlanorDeleteBeamHoppingPlan, describing a change to a modem’s beam hopping plan. -
SetRouteorDeleteRoute, describing a change to a routing table. -
SetSrPolicyorDeleteSrPolicy, describing a change to a segment-routing policy.
SetBeam, DeleteBeam
SetBeamHoppingPlan, DeleteBeamHoppingPlan
SetRoute, DeleteRoute
SetSrPolicy, 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.
In such a case, 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 understand 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 places the message in the sequence of ordered operations.
The first operation will be annotated with a sequence number of 1, and each following message will have a sequence number one greater than that of the previous message.
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 (a restart of the agent may wipe its schedule, for example).
In such an instance, it is important that operations intended to be executed on the agent’s schedule before the event are not executed on the impacted schedule.
To enforce this, the scheduling service utilizes “schedule-manipulation tokens.”
On startup or reset, an agent generates a unique schedule-manipulation token and reports it to Spacetime in a call to Reset.
All CreateEntryRequest, DeleteEntryRequest, and FinalizeRequest 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.