Writing a cloud provider

What a provider has to do#

public interface ISaveCloudProvider
{
    string Name { get; }
    CloudCapabilities Capabilities { get; }
    CloudAccountState Account { get; }
    string AccountMessage { get; }

    CloudConnectRequest Connect();
    CloudUploadRequest Upload(CloudUploadSpec spec);
    CloudDownloadRequest Download(string remoteKey);
    CloudListRequest List();
    CloudDeleteRequest Delete(string remoteKey);
}

Five operations, and nothing about saves in any of them: bytes out, bytes in. Everything a save system has to get right — deciding which copy wins, refusing to overwrite a copy that moved, remembering what was uploaded, queueing an offline save, retrying — is above the seam and is the same for every provider.

Requests are polled, not blocked on#

PersistKit's runtime does no work off the main thread, so an operation has to make progress while the game runs:

public CloudDownloadRequest Download(string remoteKey)
{
    var request = new CloudDownloadRequest(remoteKey);

    request.Attach(r =>                       // one step, called whenever the request is read
    {
        if (r.CancelRequested) { r.CompleteAsCancelled(class="tok-str">"the download"); return false; }
class="tok-com">
        // …start your request, then complete when it is done:
        r.Complete(PersistResult.Success(true));
        return true;
    });

    return request;
}

Attach, Complete, CompleteAsCancelled and ReportProgress are public for exactly this reason. A game uses IsDone, Progress, Result, Cancel() and yield return request.WaitForCompletion().

Four rules that make a provider a good citizen#

1. Never throw for an expected failure. A network problem is a PersistResult with a code. A thrown exception inside a provider is treated as a defect.
2. Declare your capabilities honestly. CloudCapabilities.ConditionalWrite is what makes a lost race a reported conflict instead of a silent overwrite. Claiming it without doing it is how one device destroys another's save.
3. Report metadata when you can by implementing ISaveCloudMetadataProvider, so a sync compares two copies without downloading one to find out what it is.
4. Write in a way that cannot half-replace a save. The folder provider writes a .part file and promotes it; the REST provider uses If-Match so the endpoint refuses a stale write.

What each service would take#

Not verified Those four are described, not implemented. None could be exercised here — each needs an account, a plan or a platform SDK — so no claim is made for any of them, and nothing in the package references their SDKs.

Testing a provider without a network#

MemoryCloudProvider is the double the package's own cloud behaviour is verified against: it can be offline, made slow, made to refuse, and shared between two instances so that "the same save on two devices" is a real test. That verifies PersistKit, not your service: a provider still has to be tested against the real thing.

Next#

• Cloud saves
• Error codes