SyncAPI
TopThe Sync API allows clients to collaboratively read and write JSON data to a shared resource.
CreateSynapseConnection()
Create a synapse connection resource.
A synapse connection defines a bi-directional syncronisation between two Volt databases. The connection is created as a child of the local synapse resource, and a symbolic link is also placed in the system-wide 'connection' folder.
The remote Volt is identified by its DID or address. If a relay address is provided, the connection will be established via the relay.
The authenticated account must have `volt:resource-create` access to the local synapse resource.
SetSynapseDocumentMetadata()
Set the metadata for a synapse document.
SyncDocument()
Bidirectional streaming RPC for real-time document synchronization
WatchSynapsePath()
Watch synapse paths for changes.
WriteSynapsePath()
Write a single value to a given synapse JSON path.
SetSynapseDocumentMetadataRequest
| Field | Type | Description |
| database_id | string | The id of the synapse. |
| document_id | string | The id of the document to set the metadata for. |
| metadata | SynapseDocumentMetadata repeated | The metadata to set for the document. |
| json | string | Any additional application-specific JSON to attach to the document. |
SetSynapseDocumentMetadataResponse
| Field | Type | Description |
| status | Status |
SynapseDocumentMetadata
| Field | Type | Description |
| name | string | The name of the top-level shared type in the document. |
| type | string | The type of the shared type, e.g. "map", "array" or "text". |
| json_schema | string | The JSON schema that describes the data that is stored in this shared type. |
SyncDocumentRequest
| Field | Type | Description |
| sync_start | SyncDocumentStart | Initial sync configuration, must be sent as first message. |
| update | SyncDocumentUpdate | Updates to apply to the remote document. |
| sync_state | SyncState | The sync state of the local document |
SyncDocumentResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
| state_vector | bytes | The state vector of the Volt (remote) document. Only present in the initial response. |
| update | SyncDocumentUpdate | Updates to apply to client (local) document. |
| sync_state | SyncState | The sync state of the Volt (remote) document |
| is_read_only | bool | Set to true if the client is in read-only mode. Only present in the initial response. |
SyncDocumentStart
| Field | Type | Description |
| database_id | string | The id of the database that contains the document. |
| document_id | string | The id of the document to sync. |
| state_vector | bytes | The clients state vector. The Volt will respond with updates that should be applied to the local document. |
| read_only | bool | Set to true to only receive updates from other clients. |
| read_only_fallback | bool | Set to true to downgrade to read-only access if the client does not have write access. |
SyncDocumentUpdate
| Field | Type | Description |
| chunk | bytes | |
| complete | bool |
WatchSynapsePathRequest
| Field | Type | Description |
| start | WatchSynapsePathStart | Start watching the given paths; must be sent as the first message. |
| stop | bool | Request to stop the watch. |
WatchSynapsePathResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
| update | WatchSynapsePathUpdate | The update to the path. |
WatchSynapsePathStart
Parameters to start watching synapse paths. Sent as the first message.
| Field | Type | Description |
| database_id | string | The id of the database that contains the document. |
| document_id | string | The id of the document to watch. |
| path | string repeated | The JSON paths to watch. |
WatchSynapsePathUpdate
| Field | Type | Description |
| watch_path | string | The JSON path that was updated. |
| event_path | string | The actual JSON path for this match (e.g. $.content["Atlantic Star"].lat). Enables clients to identify which array element or map key the update refers to when using wildcard matches such as $.content[*] |
| update_type | SynapsePathUpdateType | The type of update. |
| value | string | The JSON value that was updated. |
| previous_value | string | The previous JSON value before the update. |
| index | uint32 | The zero-based index of the update. |
| total | uint32 | The total number of updates. |
WriteSynapsePathRequest
| Field | Type | Description |
| database_id | string | The id of the database that contains the document. |
| document_id | string | The id of the document to write to. |
| path | string | The JSON path to write to. |
| json | string | The JSON value to write. |
WriteSynapsePathResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
SynapsePathUpdateType
| Name | Number | Description |
| SYNAPSE_PATH_UPDATE_TYPE_UNKNOWN | 0 | |
| SYNAPSE_PATH_UPDATE_TYPE_ADD | 1 | |
| SYNAPSE_PATH_UPDATE_TYPE_UPDATE | 2 | |
| SYNAPSE_PATH_UPDATE_TYPE_DELETE | 3 |
SyncState
| Name | Number | Description |
| SYNC_STATE_UNKNOWN | 0 | |
| SYNC_STATE_SYNCING | 1 | |
| SYNC_STATE_DONE | 2 | |
| SYNC_STATE_UPDATE | 3 | |
| SYNC_STATE_AWARENESS | 4 |
Scalar Value Types
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
| double | double | double | float | float64 | double | float | Float | |
| float | float | float | float | float32 | float | float | Float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |