Synchronizing

Connections

A CalendarConnection is a calendar of someone's, linked to the site:

The application keeps its connections and gives them through Contract\ConnectionRepository. A connection holds no credential.

Credentials

Contract\CredentialStore gives the Credentials of a connection at each call: Credentials::bearer() for an OAuth access token, Credentials::basic() for a user name and an application password, Credentials::none() for a feed.

The application obtains the tokens, keeps them encrypted, and refreshes them before giving them. The package never keeps them: Credentials cannot be serialised, and a dump of it shows its kind only. When a service refuses them, ProviderFailed::isUnauthorized() is true, so the application can refresh the token, or ask the member to link the calendar again.

Busy times

CalendarSync::refreshBusy() reads the busy periods of a connection within a SyncWindow — at most 400 days —, cuts them to the window, sorts them and joins those that overlap or touch, then gives them to Contract\BusyStore, which replaces what the connection had in that window. A joined period is tentative only when all it joins are.

When the service fails, or its answer cannot be read, the exception is thrown before the store is called: the periods read last stay as they were. A calendar that gives more than 10,000 periods in a window is refused rather than half read, as a calendar half read would leave times free that are not.

A BusyPeriod holds a start, an end, in UTC, and whether it is tentative. Nothing else is read from the calendar, so nothing else can be stored.

Events written

CalendarSync::publish() writes an OutboundEvent into a connection; writing the same identifier again replaces it. CalendarSync::withdraw() removes it; an event that is not there is not an error.

An OutboundEvent holds:

What the event shows is the application's choice: a site that only blocks the time writes a title such as "Busy" and nothing else.

Messages

Two messages let a worker do the synchronizing, each carrying identifiers only:

RefreshBusyTimes::of($connectionId, $from, $days) writes the start as DateTimeInterface::ATOM. Because the handler of SyncEvent reads the event when it runs, a message sent before a change writes the change, and one sent for an event deleted since removes it.

Failures

All implement Exception\CalendarSyncException. Their messages name the adapter and the status, never an address, a token or a body — the address of a feed can be its secret —, and a transport error is not chained, as its message can hold the address.