fuchsia.ledger

PROTOCOLS

Syncable

Defined in fuchsia.ledger/ledger.fidl

Base interface for all services offered by the Ledger.

In case of an unexpected error on one of the service offered by the Ledger, the service will close the connected channel, sending a zx.status as an epitaph.

If a client needs to ensure a sequence of operation has been processed by the service, it can issue a Sync command. The response will be send once all request started before the Sync request has been processed by the service.

Sync

Request

NameType

Response

NameType

Ledger

Defined in fuchsia.ledger/ledger.fidl

Sync

Request

NameType

Response

NameType

GetPage

Retrieves the page with the given identifier, creating it if needed, and binds page_request to it. A null identifier can be passed to create a new page with a random unique identifier. It is allowed to connect to the same page concurrently multiple times.

Parameters: id the identifier of the page, or null to create a new page with a random identifier.

Request

NameType
id PageId?
page_request request<Page>

GetRootPage

Gets the page with identifier [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]. This is a convenience method equivalent to: GetPage([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], page_request).

Request

NameType
page_request request<Page>

SetConflictResolverFactory

Sets the ConflictResolverFactory to use for resolving conflicts on pages. If this method has never been called, a last-one-wins policy will be used for every page. If this method is called multiple times, the factories are kept and conflict resolver requests are sent to one of the connected factories. If all factories are later disconnected, pages that already have a conflict resolution strategy (because they were opened before the factory disconnected) will continue using their current strategy. The pages for which no conflict resolution is set up will not get their conflicts resolved until this method is called again.

Request

NameType
factory ConflictResolverFactory

Page

Defined in fuchsia.ledger/ledger.fidl

A page is the smallest unit of syncable data.

Sync

Request

NameType

Response

NameType

GetId

Returns the identifier for the page.

Request

NameType

Response

NameType
id PageId

GetSnapshot

Creates a snapshot of the page, allowing the client app to read a consistent view of the content of the page. If key_prefix is provided, the resulting snapshot includes only the entries with matching keys.

If watcher is provided, it will receive notifications for changes of the page state on this page connection newer than the resulting snapshot. Change notifications will only contain the entries matching key_prefix. To receive all changes, use an empty key_prefix.

Request

NameType
snapshot_request request<PageSnapshot>
key_prefix vector<uint8>[256]
watcher PageWatcher?

Put

Mutations are bundled together into atomic commits. If a transaction is in progress, the list of mutations bundled together is tied to the current transaction. If no transaction is in progress, mutations will be bundled with the following rules: - A call to either GetSnapshot() or StartTransaction() will commit any pending mutations. - All pending mutations will regularly be bundled together and committed. They are guaranteed to be persisted as soon as the client receives a successful status. Put() and PutWithPriority() can be used for small values that fit inside a FIDL message. If the value is bigger, a reference must be first created using CreateReferenceFromSocket() or CreateReferenceFromBuffer() and then PutReference() can be used. PutWithPriority() and PutReference() have an additional priority parameter managing the synchronization policy for this value. Put() uses a default priority of Priority.EAGER. For the list of available priorities and their definition, see Priority.

Request

NameType
key vector<uint8>[256]
value vector<uint8>

PutWithPriority

Request

NameType
key vector<uint8>[256]
value vector<uint8>
priority Priority

PutReference

Request

NameType
key vector<uint8>[256]
reference Reference
priority Priority

Delete

Request

NameType
key vector<uint8>[256]

Clear

Deletes all entries in the page. Outside of a transaction, this operation is equivalent to deleting every key currently present on the page in a single transaction. In a transaction, this operation is equivalent to deleting every key present in the page before the transaction, as well as any new key added since the transaction started.

Request

NameType

CreateReferenceFromSocket

Creates a new reference. The object is not part of any commit. It must be associated with a key using PutReference(). The content of the reference will be the content of the socket. The content size must be equal to size, otherwise the call will fail.

Request

NameType
size uint64
data handle<socket>

Response

NameType
result Page_CreateReferenceFromSocket_Result

CreateReferenceFromBuffer

Creates a new reference. The object is not part of any commit. It must be associated with a key using PutReference(). The content of the reference will be the content of the buffer.

Request

NameType
buffer fuchsia.mem/Buffer

Response

NameType
result Page_CreateReferenceFromBuffer_Result

StartTransaction

Transactions allow the client to ensures changes are seen atomically by observers of this page. Once a transaction is started with StartTransaction(), every call to Put(...) and Delete(...) will not be visible until either Commit() is called, and all changes are applied in a single commit, or Rollback() is called and all changes are discarded.

Parallel transactions on the same page connection are not allowed, and calling StartTransaction() when a transaction is already in progress returns an error. However, a client is free to connect to the same page multiple times, and run parallel transactions on the same page using separate connections. In this case, committing each transaction creates divergent commits, which are later subject to conflict resolution.

When a transaction is in progress, the page content visible on this page connection is pinned to the state from when StartTransaction() was called. In particular, no watch notifications are delivered, and the conflict resolution is not invoked while the transaction is in progress. If conflicting changes are made or synced while the transaction is in progress, conflict resolution is invoked after the transaction is committed.

Starting a transaction will block until all watchers registered on this page connection have received the current page state, ie. the one that will be used as the base of the transaction. Put (with all its variants) and Delete calls may be pipelined while StartTransaction() is pending and will be taken into account in the transaction while it is pending.

Request

NameType

Commit

Request

NameType

Rollback

Request

NameType

SetSyncStateWatcher

Sets a watcher to track the synchronisation state of this page. The current state is immediately sent to the watcher when this method is called.

Request

NameType
watcher SyncWatcher

WaitForConflictResolution

Waits until all conflicts are resolved before calling the callback. The client can call this method multiple times, even before the previous calls are completed. Callbacks will be executed in the order they were added and indicate whether a merge happened between the callback registration and its execution. If there are no pending conflicts at the time this is called, the callback gets executed right away.

Request

NameType

Response

NameType
wait_status ConflictResolutionWaitStatus

PageSnapshot

Defined in fuchsia.ledger/ledger.fidl

The content of a page at a given time. Closing the connection to a Page interface closes all PageSnapshot interfaces it created. The contents provided by this interface are limited to the prefix provided to the Page.GetSnapshot() call.

Sync

Request

NameType

Response

NameType

GetEntries

Returns the entries in the page with keys greater or equal to key_start using the lexicographic order. If key_start is empty, all entries are returned. If the result fits in a single fidl message, next_token will be equal to NULL. Otherwise, next_token will have a non-NULL value. To retrieve the remaining results, another call to GetEntries should be made, initializing the optional token argument with the value of next_token returned in the previous call. next_token will not be NULL as long as there are more results and NULL once finished. Only EAGER values are guaranteed to be returned inside entries. Missing LAZY values can be retrieved over the network using Fetch(). The returned entries are sorted by key.

Request

NameType
key_start vector<uint8>[256]
token Token?

Response

NameType
entries vector<Entry>[65536]
next_token Token?

GetEntriesInline

Same as GetEntries(). The connection will be closed with a ZX_ERR_BAD_STATE epitaph if a value does not fit in a FIDL message.

Request

NameType
key_start vector<uint8>[256]
token Token?

Response

NameType
entries vector<InlinedEntry>[65536]
next_token Token?

GetKeys

Returns the keys of all entries in the page which are greater or equal to key_start using the lexicographic order. If key_start is empty, all keys are returned. The returned keys are sorted. If the result fits in a single fidl message, next_token will be equal to NULL. Otherwise, next_token will have a non-NULL value. To retrieve the remaining results, another call to GetKeys should be made, initializing the optional token argument with the value of next_token returned in the previous call. next_token will not be NULL as long as there are more results and NULL once finished.

Request

NameType
key_start vector<uint8>[256]
token Token?

Response

NameType
keys vector<vector>[65536]
next_token Token?

Get

Returns the value of a given key. Only EAGER values are guaranteed to be returned. Calls when the value is LAZY and not available will return a NEEDS_FETCH status. The value can be retrieved over the network using a Fetch() call.

Request

NameType
key vector<uint8>[256]

Response

NameType
result PageSnapshot_Get_Result

GetInline

Returns the value of a given key if it fits in a FIDL message. The connection will be closed with a ZX_ERR_BAD_STATE epitaph if the value does not fit in a FIDL message. See Get() for additional information.

Request

NameType
key vector<uint8>[256]

Response

NameType
result PageSnapshot_GetInline_Result

Fetch

Fetches the value of a given key, over the network if not already present locally. NETWORK_ERROR is returned if the download fails (e.g.: network is not available).

Request

NameType
key vector<uint8>[256]

Response

NameType
result PageSnapshot_Fetch_Result

FetchPartial

Fetches the value of a given key, over the network if not already present locally, and returns a shared handle of a part of the value of a given key, starting at the position that is specified by offset. If offset is less than 0, starts at -offset from the end of the value. Returns at most max_size bytes. If max_size is less than 0, returns everything.

Request

NameType
key vector<uint8>[256]
offset int64
max_size int64

Response

NameType
result PageSnapshot_FetchPartial_Result

PageWatcher

Defined in fuchsia.ledger/ledger.fidl

Interface to watch changes to a page. The client will receive changes made by itself, as well as other clients or synced from other devices. The contents of a transaction will never be split across multiple OnChange() calls, but the contents of multiple transactions may be merged into one OnChange() call.

OnChange

Called for changes made on the page. If the result fits in a single fidl message, result_state will be COMPLETED. Otherwise, OnChange will be called multiple times and result_state will be PARTIAL_STARTED the first time, PARTIAL_CONTINUED the following ones and finally PARTIAL_COMPLETED on the last call. No new OnChange() call will be made while the previous one is still active. If clients are interested in the full content of the page at the time of the change, they can request a PageSnapshot in the callback. This request is optional and can be requested in any partial (started, continued or completed) and/or COMPLETED OnChange call. In any case, all requests made on a sequence of OnChange calls for the same page change, will always return the same snapshot: the one including all changes.

Note that calls to Page.StartTransaction() on the page connection on which the watcher was registered will block until all OnChange() calls have finished.

Request

NameType
page_change PageChange
result_state ResultState

Response

NameType
snapshot request<PageSnapshot>?

ConflictResolverFactory

Defined in fuchsia.ledger/ledger.fidl

This interface lets clients control the conflict resolution policy of the ledger. It allows them to either use pre-defined policies, or provide their own implementation. This can be decided on a page-by-page basis.

GetPolicy

Returns the conflict resolution policy for the given page.

Request

NameType
page_id PageId

Response

NameType
policy MergePolicy

NewConflictResolver

Returns a ConflictResolver to use for the given page. This will only be called if GetPolicy for the same page returned AUTOMATIC_WITH_FALLBACK or CUSTOM.

Request

NameType
page_id PageId
resolver request<ConflictResolver>

MergeResultProvider

Defined in fuchsia.ledger/ledger.fidl

A merge result provider, obtained from ConflictResolver.Resolve(). Can be used to retrieve data about the conflict, and provide the merge result. When all changes have been sent, Done() should be called to mark the end of incoming merge changes.

Sync

Request

NameType

Response

NameType

GetFullDiff

GetFullDiff returns the set of all key/value pairs (entries) that have been modified between the common ancestor (see ConflictResolver.Resolve()) and the left and right branches.

Values of LAZY keys may not be present on the device. In that case, the corresponding Value objects within DiffEntry will have a NULL value field. If needed, left and right, provided by the ConflictResolver.Resolve() method can be used by clients to Fetch these values. If a key is not present at all in one of the branches, its corresponding Value object will be NULL.

The first call to get the DiffEntrys should be done using a NULL token. If the result does not fit in a single fidl message, next_token will have a non-NULL value, which can be used to retrieve the rest of the results by calling GetFullDiff() with that token.

Request

NameType
token Token?

Response

NameType
changes vector<DiffEntry>[65536]
next_token Token?

GetConflictingDiff

GetConflictingDiff returns the set of all key/value pairs that were modified on both sides to different values, or deleted on one side and modified on the other.

It behaves like GetFullDiff otherwise.

Request

NameType
token Token?

Response

NameType
changes vector<DiffEntry>[65536]
next_token Token?

Merge

Once the result of the merge has been computed Merge() can be called with all changes that resolve this conflict. If the result does not fit in a single fidl message, Merge() can be called multiple times. If any of the Merge() calls fails, i.e. status is not OK, all following calls will fail with the same error.

If a key/value pair is sent multiple times in one or several Merge() call, only the last pair is taken into account.

For all keys for which no merged value has been set (either here or through MergeNonConflictingEntries() below), the left value will be used. It is thus not necessary to send a MergedValue with a LEFT value source, unless to overwrite a previous MergedValue.

Request

NameType
merge_changes vector<MergedValue>[65536]

MergeNonConflictingEntries

Automatically merges all non conflicting entries (entries that are modified on one side only or identical on both sides). This is equivalent to sending, through Merge(), a MergedValue with a RIGHT ValueSource for all non-conflicting keys modified on the right side. Conflicting entries can still be merged using the Merge() method.

Request

NameType

Done

Marks the end of merge changes to resolve this conflict. After Done() is called MergeResultProvider interface cannot be used any more.

Request

NameType

ConflictResolver

Defined in fuchsia.ledger/ledger.fidl

Custom conflict resolver. If a ConflictResolverFactory is registered, and ConflictResolverFactory.GetPolicy() returns AUTOMATIC_WITH_FALLBACK or CUSTOM when called for a given page, the NewConflictResolver method will be called and will provide a ConflictResolver. Each time a custom conflict resolution is needed according to the chosen policy, the method ConflictResolver.Resolve() will be called, and the client will resolve the conflict by returning the final value for all conflicting keys as well as values for any other key that the client wants to change.

Resolve

Method called when a conflict needs to be resolved. left and right contain the snapshots of the two branches and common_version that of the lowest common ancestor. common_version can be NULL if this version is no longer available. The result of the merge can be given through the result_provider, using the left branch as the base of the merge commit, i.e. only key/value pairs that are different from the left version of the page should be sent. result_provider can also be used to retrieve the set of differences, i.e. conflicting keys, between the two versions.

Request

NameType
left PageSnapshot
right PageSnapshot
common_version PageSnapshot?
new_result_provider MergeResultProvider

SyncWatcher

Defined in fuchsia.ledger/ledger.fidl

Watcher interface to be implemented by clients who wish to follow the synchronization status of their ledger. SyncStateChanged callback must be called for new state change calls to be sent.

SyncStateChanged

Request

NameType
download_status SyncState
upload_status SyncState

Response

NameType

STRUCTS

Page_CreateReferenceFromSocket_Response

generated

NameTypeDescriptionDefault
reference Reference No default

Page_CreateReferenceFromBuffer_Response

generated

NameTypeDescriptionDefault
reference Reference No default

PageSnapshot_Get_Response

generated

NameTypeDescriptionDefault
buffer fuchsia.mem/Buffer No default

PageSnapshot_GetInline_Response

generated

NameTypeDescriptionDefault
value InlinedValue No default

PageSnapshot_Fetch_Response

generated

NameTypeDescriptionDefault
buffer fuchsia.mem/Buffer No default

PageSnapshot_FetchPartial_Response

generated

NameTypeDescriptionDefault
buffer fuchsia.mem/Buffer No default

PageId

Defined in fuchsia.ledger/ledger.fidl

Type of the identifier of a ledger Page.

NameTypeDescriptionDefault
id uint8[16] No default

Reference

Defined in fuchsia.ledger/ledger.fidl

A reference to a value.

NameTypeDescriptionDefault
opaque_id vector<uint8> No default

Token

Defined in fuchsia.ledger/ledger.fidl

A continuation token for paginated requests.

NameTypeDescriptionDefault
opaque_id vector<uint8> No default

Entry

Defined in fuchsia.ledger/ledger.fidl

A pair of key and value.

NameTypeDescriptionDefault
key vector<uint8>[256] No default
value fuchsia.mem/Buffer? `value` is null if the value requested has the LAZY priority and is not present on the device. Clients must use a Fetch call to retrieve the contents. No default
priority Priority No default

InlinedValue

Defined in fuchsia.ledger/ledger.fidl

A value inlined in a message.

NameTypeDescriptionDefault
value vector<uint8> No default

InlinedEntry

Defined in fuchsia.ledger/ledger.fidl

A pair of key and an inlined value.

NameTypeDescriptionDefault
key vector<uint8>[256] No default
inlined_value InlinedValue? `value` is null if the value requested has the LAZY priority and is not present on the device. Clients must use a Fetch call to retrieve the contents. No default
priority Priority No default

PageChange

Defined in fuchsia.ledger/ledger.fidl

NameTypeDescriptionDefault
timestamp int64 The timestamp of this change. This represents the number of nanoseconds since Unix epoch (i.e., since "1970-01-01 00:00 UTC", ignoring leap seconds). This value is set by the device that created the change and is not synchronized across devices. In particular, there is no guarantee that the `timestamp` of a follow up change is greater than this one's. No default
changed_entries vector<Entry>[65536] List of new and modified entries. `changed_entries` are sorted by `key`. No default
deleted_keys vector<vector>[65536] List of deleted keys, in sorted order. No default

MergedValue

Defined in fuchsia.ledger/ledger.fidl

A change in the page. If source is set to NEW, new_value must be set to the new value. If source is not NEW, new_value and priority are ignored.

NameTypeDescriptionDefault
key vector<uint8>[256] No default
source ValueSource No default
new_value BytesOrReference? No default
priority Priority No default

DiffEntry

Defined in fuchsia.ledger/ledger.fidl

An entry in a diff, as returned by MergeResultProvider.

If base, left or right are NULL, this means that the corresponding key was not present in the base, left or right (respectively) branch of the page.

NameTypeDescriptionDefault
key vector<uint8>[256] No default
base Value? No default
left Value? No default
right Value? No default

Value

Defined in fuchsia.ledger/ledger.fidl

A value in a DiffEntry.

If the value is LAZY and is not present locally, value will be NULL. The value can be retrieved using a Fetch() call on a corresponding snapshot.

NameTypeDescriptionDefault
value fuchsia.mem/Buffer? No default
priority Priority No default

ENUMS

ConflictResolutionWaitStatus

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

The result of a wait for conflict resolution. See Page.WaitForConflictResolution for details.

NameValueDescription
NO_CONFLICTS 0
CONFLICTS_RESOLVED 1

Priority

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

The synchronization priority of a reference.

NameValueDescription
EAGER 0
LAZY 1

Error

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

Error returned by the different PageSnapshot methods.

NameValueDescription
KEY_NOT_FOUND 1
NEEDS_FETCH 2
NETWORK_ERROR 3

ResultState

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

NameValueDescription
COMPLETED 0
PARTIAL_STARTED 1
PARTIAL_CONTINUED 2
PARTIAL_COMPLETED 3

MergePolicy

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

Strategy to be used when resolving conflicts.

NameValueDescription
LAST_ONE_WINS 0
AUTOMATIC_WITH_FALLBACK 1
CUSTOM 2

ValueSource

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

Source of the value used to resolve a conflict.

DELETE deletes the key; NEW creates a new value; RIGHT selects the value from the right branch. If no value is sent, the left branch is selected. Used by MergedValue.

NameValueDescription
RIGHT 0
NEW 1
DELETE 2

SyncState

Type: uint32

Defined in fuchsia.ledger/ledger.fidl

Synchronization state.

NameValueDescription
IDLE 0
PENDING 1
IN_PROGRESS 2
ERROR 3

UNIONS

Page_CreateReferenceFromSocket_Result

generated

NameTypeDescription
response Page_CreateReferenceFromSocket_Response
err int32

Page_CreateReferenceFromBuffer_Result

generated

NameTypeDescription
response Page_CreateReferenceFromBuffer_Response
err int32

PageSnapshot_Get_Result

generated

NameTypeDescription
response PageSnapshot_Get_Response
err Error

PageSnapshot_GetInline_Result

generated

NameTypeDescription
response PageSnapshot_GetInline_Response
err Error

PageSnapshot_Fetch_Result

generated

NameTypeDescription
response PageSnapshot_Fetch_Response
err Error

PageSnapshot_FetchPartial_Result

generated

NameTypeDescription
response PageSnapshot_FetchPartial_Response
err Error

BytesOrReference

Defined in fuchsia.ledger/ledger.fidl

A value that is either small enough to be directly embedded in bytes or that is referenced by reference.

NameTypeDescription
bytes vector<uint8>
reference Reference

CONSTANTS

NameValueTypeDescription
NO_LINT 65536 uint32
PAGE_ID_SIZE 16 uint32 Size in bytes of Page IDs.