@dxos/protocols 0.1.0

package/src/proto/dxos/devtools/host.proto

@@ -0,0 +1,294 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+import "dxos/devtools/swarmLog.proto";
+
+import "dxos/echo/timeframe.proto";
+import "google/protobuf/empty.proto";
+
+import "dxos/echo/feed.proto";
+import "dxos/echo/snapshot.proto";
+import "dxos/halo/keys.proto";
+import "dxos/halo/signed.proto";
+import "dxos/keys.proto";
+import "dxos/rpc.proto";
+
+package dxos.devtools.host;
+
+//
+// DevtoolsHost
+//
+
+service DevtoolsHost {
+  //
+  // General
+  //
+
+  // Subscribe to server-to-client events.
+  rpc Events(google.protobuf.Empty) returns (stream Event);
+
+  // Get client config.
+  rpc GetConfig(google.protobuf.Empty) returns (GetConfigResponse);
+
+  rpc ResetStorage(ResetStorageRequest) returns (google.protobuf.Empty);
+
+  rpc EnableDebugLogging(EnableDebugLoggingRequest) returns (EnableDebugLoggingResponse);
+  rpc DisableDebugLogging(EnableDebugLoggingRequest) returns (EnableDebugLoggingResponse);
+
+  //
+  // HALO
+  //
+
+  rpc SubscribeToKeyringKeys(SubscribeToKeyringKeysRequest) returns (stream SubscribeToKeyringKeysResponse);
+
+  rpc SubscribeToCredentialMessages(SubscribeToCredentialMessagesRequest) returns (stream SubscribeToCredentialMessagesResponse);
+
+  //
+  // ECHO
+  //
+
+  rpc SubscribeToParties(SubscribeToPartiesRequest) returns (stream SubscribeToPartiesResponse);
+  rpc SubscribeToItems(SubscribeToItemsRequest) returns (stream SubscribeToItemsResponse);
+  rpc SubscribeToFeeds(SubscribeToFeedsRequest) returns (stream SubscribeToFeedsResponse);
+  rpc SubscribeToFeedBlocks(SubscribeToFeedBlocksRequest) returns (stream SubscribeToFeedBlocksResponse);
+
+  rpc GetPartySnapshot(GetPartySnapshotRequest) returns (GetPartySnapshotResponse);
+  rpc SavePartySnapshot(SavePartySnapshotRequest) returns (SavePartySnapshotResponse);
+  rpc ClearSnapshots(ClearSnapshotsRequest) returns (google.protobuf.Empty);
+
+  //
+  // MESH
+  //
+
+  rpc GetNetworkPeers(GetNetworkPeersRequest) returns (GetNetworkPeersResponse);
+  rpc SubscribeToNetworkTopics(google.protobuf.Empty) returns (stream SubscribeToNetworkTopicsResponse);
+  rpc SubscribeToSignalStatus(google.protobuf.Empty) returns (stream SubscribeToSignalStatusResponse);
+  rpc SubscribeToSignalTrace(google.protobuf.Empty) returns (stream SubscribeToSignalTraceResponse);
+  rpc SubscribeToSwarmInfo(SubscribeToSwarmInfoRequest) returns (stream SubscribeToSwarmInfoResponse);
+}
+
+message Event {
+  oneof payload {
+    ReadyEvent ready = 1;
+  }
+}
+
+message ReadyEvent {}
+
+message GetConfigResponse {
+  // JSON-encoded configuration object.
+  string config = 1;
+}
+
+// EnableDebugLogging
+
+message EnableDebugLoggingRequest {
+  optional string namespaces = 1;
+}
+
+message EnableDebugLoggingResponse {
+  optional string enabled_namespaces = 1;
+}
+
+// DisableDebugLogging
+
+message DisableDebugLoggingRequest {
+  optional string namespaces = 1;
+}
+
+message DisableDebugLoggingResponse {
+  optional string enabled_namespaces = 1;
+}
+
+// SubscribeToKeyringKeys
+
+message SubscribeToKeyringKeysRequest {}
+
+message SubscribeToKeyringKeysResponse {
+  repeated dxos.halo.keys.KeyRecord keys = 1;
+}
+
+// SubscribeToCredential
+
+message SubscribeToCredentialMessagesRequest {
+  optional dxos.keys.PublicKey party_key = 1;
+}
+
+message SubscribeToCredentialMessagesResponse {
+  repeated dxos.halo.signed.SignedMessage messages = 1;
+}
+
+// ResetStorage
+
+message ResetStorageRequest {}
+
+// GetNetworkPeers
+
+message GetNetworkPeersRequest {
+  bytes topic = 1;
+}
+
+message GetNetworkPeersResponse {
+  message PeerInfo {
+   dxos.keys.PublicKey id = 1;
+
+    // PeerState enum.
+    string state = 2;
+
+    repeated bytes connections = 3;
+  }
+
+  repeated PeerInfo peers = 1;
+}
+
+// SubscribeToParties
+
+message SubscribeToPartiesRequest {
+  repeated dxos.keys.PublicKey party_keys = 1;
+}
+
+message SubscribeToPartiesResponse {
+  message PartyInfo {
+    dxos.keys.PublicKey key = 1;
+    bool is_open = 2;
+    dxos.echo.timeframe.TimeframeVector timeframe = 3;
+    dxos.keys.PublicKey genesisFeed = 4;
+    dxos.keys.PublicKey controlFeed = 5;
+    dxos.keys.PublicKey dataFeed = 6;
+  }
+
+  repeated PartyInfo parties = 1;
+}
+
+// SubscribeToItems
+
+message SubscribeToItemsRequest {}
+
+message SubscribeToItemsResponse {
+  // JSON-encoded payload.
+  string data = 1;
+}
+
+// SubscribeToFeeds
+
+message SubscribeToFeedsRequest {
+  repeated dxos.keys.PublicKey feed_keys = 1;
+}
+
+message SubscribeToFeedsResponse {
+  message Feed {
+   dxos.keys.PublicKey feed_key = 1;
+    int32 length = 2;
+  }
+
+  repeated Feed feeds = 1;
+}
+
+// SubscribeToFeedMessages
+
+message SubscribeToFeedBlocksRequest {
+  optional dxos.keys.PublicKey party_key = 1;
+  optional dxos.keys.PublicKey feed_key = 2;
+  optional int32 max_blocks = 3;
+}
+
+message SubscribeToFeedBlocksResponse {
+  message Block {
+    dxos.keys.PublicKey feed_key = 1;
+    int32 seq = 2;
+    dxos.echo.feed.FeedMessage data = 3;
+  }
+
+  repeated Block blocks = 1;
+}
+
+// GetPartySnapshot
+
+message GetPartySnapshotRequest {
+  dxos.keys.PublicKey party_key = 1;
+}
+
+message GetPartySnapshotResponse {
+  optional dxos.echo.snapshot.PartySnapshot snapshot = 1;
+}
+
+// SavePartySnapshot
+
+message SavePartySnapshotRequest {
+  dxos.keys.PublicKey party_key = 1;
+}
+
+message SavePartySnapshotResponse {
+  optional dxos.echo.snapshot.PartySnapshot snapshot = 1;
+}
+
+// ClearSnapshots
+
+message ClearSnapshotsRequest {}
+
+// SubscribeToNetworkTopics
+
+message SubscribeToNetworkTopicsResponse {
+  message Topic {
+   dxos.keys.PublicKey topic = 1;
+    optional string label = 2;
+  }
+
+  repeated Topic topics = 1;
+}
+
+// SubscribeToSignalStatus
+
+message SubscribeToSignalStatusResponse {
+  message SignalServer {
+    string host = 1;
+
+    // SignalApi.State enum.
+    string state = 2;
+
+    optional string error = 3;
+
+    // Number of milliseconds before reconnection.
+    // TODO(dmaretskyi): Represent as absolute timestamp.
+    int32 reconnect_in = 4;
+
+    // TODO(dmaretskyi): Change to timestamp.
+    int32 connection_started = 5;
+    int32 last_state_change = 6;
+  }
+
+  repeated SignalServer servers = 1;
+}
+
+// SubscribeToSignalTrace
+
+message SubscribeToSignalTraceResponse {
+  // JSON-encoded events.
+  repeated string events = 1;
+}
+
+// SubscribeToSwarmInfo
+
+message SubscribeToSwarmInfoRequest {}
+
+message SubscribeToSwarmInfoResponse {
+  repeated SwarmInfo data = 1;
+}
+
+//
+// TracingService
+//
+
+service TracingService {
+  rpc SetTracingOptions(SetTracingOptionsRequest) returns (google.protobuf.Empty);
+  rpc SubscribeToRpcTrace (google.protobuf.Empty) returns (stream dxos.rpc.RpcMessage);
+}
+
+// SetTracingOptions
+
+message SetTracingOptionsRequest {
+  bool enable = 1;
+}

package/src/proto/dxos/devtools/swarmLog.proto

@@ -0,0 +1,32 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+import "dxos/keys.proto";
+
+package dxos.devtools.swarmLog;
+
+message SwarmInfo {
+  dxos.keys.PublicKey id = 1;
+  dxos.keys.PublicKey topic = 2;
+  optional string label = 3;
+  bool is_active = 4;
+  repeated ConnectionInfo connections = 5;
+}
+
+message ConnectionInfo {
+  string state = 1;
+  dxos.keys.PublicKey session_id = 2;
+  dxos.keys.PublicKey remote_peer_id = 3;
+  optional string transport = 4;
+  repeated string protocol_extensions = 5;
+  repeated ConnectionEvent events = 6;
+}
+
+message ConnectionEvent {
+  string type = 1;
+  optional string newState = 2;
+  optional string error = 3;
+}

package/src/proto/dxos/echo/feed.proto

@@ -0,0 +1,83 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+
+import "dxos/halo/credentials.proto";
+import "dxos/echo/snapshot.proto";
+import "dxos/echo/timeframe.proto";
+
+// TODO(burdon): Standardize position of "package" (i.e., before/after imports).
+// TODO(burdon): Move Item specific to echo.item?
+package dxos.echo.feed;
+
+/**
+ * Outer message type decoded by Codec.
+ * This is what is written to the feeds.
+ */
+message FeedMessage {
+  dxos.echo.timeframe.TimeframeVector timeframe = 1;
+  google.protobuf.Any payload = 2;
+}
+
+/**
+ * A container for dxos.credentials.Message
+ */
+message CredentialsMessage {
+  dxos.halo.credentials.Credential credential = 1;
+}
+
+/**
+ * Wrapper for all ECHO messages.
+ */
+// TODO(burdon): Reconcile with HaloMessage (and other "Message" types).
+message EchoEnvelope {
+  string item_id = 1;
+
+  // Create item.
+  optional ItemGenesis genesis = 10;
+
+  // Item system mutations.
+  optional ItemMutation item_mutation = 11;
+
+  // Model-specific mutations.
+  optional bytes mutation = 12;
+
+  /// Set the model to the provided snapshot.
+  optional snapshot.ModelSnapshot snapshot = 13;
+}
+
+// TODO(burdon): Document (different from parent/child).?
+// TODO(dmaretskyi): Refactor so that entity mutation message is oneof between item mutation and link mutation: items have parents, and links have from/to.
+message LinkData {
+  string source = 1;
+  string target = 2;
+}
+
+/**
+ * Item creation.
+ */
+// TODO(burdon): EntityGenesis?
+message ItemGenesis {
+  optional string item_type = 1;
+  string model_type = 2;
+  optional string model_version = 3;
+  optional LinkData link = 4;
+}
+
+/**
+ * Item mutation.
+ */
+message ItemMutation {
+  enum Action {
+    NOOP = 0;
+    DELETE = 1;
+    RESTORE = 2;
+  }
+
+  optional string parent_id = 1;  // TODO(burdon): Define Action type?
+  optional Action action = 2;
+}

package/src/proto/dxos/echo/metadata.proto

@@ -0,0 +1,51 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+
+import "dxos/echo/timeframe.proto";
+import "dxos/halo/credentials.proto";
+import "dxos/keys.proto";
+
+package dxos.echo.metadata;
+
+message EchoMetadata {
+  /**
+   * Version number that is inceremnted every time there's a breaking change to the storage schema.
+   * This is used to detect if the storage schema has changed since the last time the client was run.
+   * Loading data from a different version will might result in an error.
+   */
+  int32 version = 1;
+
+  google.protobuf.Timestamp created = 2;
+  google.protobuf.Timestamp updated = 3;
+
+  // TODO(dmaretskyi): Store the device key associated with the identity.
+  optional dxos.halo.credentials.IdentityRecord identity = 10;
+
+  /// List of the data parties.
+  repeated PartyMetadata parties = 11;
+}
+
+// TODO(dmaretskyi): Cleanup numbering.
+message PartyMetadata {
+  /// Party key.
+  dxos.keys.PublicKey key = 1;
+
+  optional dxos.keys.PublicKey genesis_feed_key = 6;
+
+  /// Key of the wriatable control feed.
+  optional dxos.keys.PublicKey control_feed_key = 4;
+
+  /// List of all feed associated with the party.
+  repeated dxos.keys.PublicKey feed_keys = 2;
+
+  /// Key of the wriatable data feed.
+  optional dxos.keys.PublicKey data_feed_key = 3;
+
+  // Latest timeframe reached while processing party messages.
+  optional timeframe.TimeframeVector latest_timeframe = 5;
+}

package/src/proto/dxos/echo/model/messenger.proto

@@ -0,0 +1,13 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.echo.model.messenger;
+
+message Message {
+  string timestamp = 1;
+  string text = 2;
+  string sender = 3;
+}

package/src/proto/dxos/echo/model/object.proto

@@ -0,0 +1,123 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.echo.model.object;
+
+//
+// Object mutation messages.
+// https://developers.google.com/protocol-buffers/docs/proto#updating
+// https://developers.google.com/protocol-buffers/docs/proto3#json
+//
+
+/**
+ * Generic value.
+ */
+message Value {
+  oneof Type {
+    bool null                         = 1;    // Explicit null vs undefined.
+
+    bool bool                         = 2;
+    int64 int                         = 3;
+    float float                       = 4;
+    string string                     = 5;
+
+    string timestamp                  = 10;   // https://en.wikipedia.org/wiki/Unix_time
+    string datetime                   = 11;   // https://en.wikipedia.org/wiki/ISO_8601 (e.g., "2019-10-25T18:48:16Z")
+    bytes bytes                       = 12;
+
+    KeyValueObject object             = 20;
+    Array array                       = 21;
+  }
+}
+
+/**
+ * Ordered collection of values.
+ */
+message Array {
+  repeated Value values               = 1;
+}
+
+/**
+ * Key x Value tuple.
+ */
+message KeyValue {
+  string key                          = 1;
+  Value value                         = 2;
+}
+
+/**
+ * Object data definition.
+ */
+message KeyValueObject {
+  repeated KeyValue properties        = 1;
+}
+
+/**
+ * Query predicate.
+ */
+message Predicate {
+  enum Operation {
+    OR                                = 0;
+    AND                               = 1;
+    NOT                               = 2;    // === NOT AND (NAND)
+
+    IN                                = 10;
+    EQUALS                            = 11;   // Exact
+    GTE                               = 12;
+    GT                                = 13;
+    LTE                               = 14;
+    LT                                = 15;
+
+    PREFIX_MATCH                      = 20;   // String prefix (case insensitive).
+    TEXT_MATCH                        = 21;   // Simple prefix word match.
+  }
+
+  Operation op                        = 1;
+  optional string key                 = 2;
+  optional Value value                = 3;
+  repeated Predicate predicates       = 4;
+}
+
+/**
+ * Query.
+ */
+message Query {
+  Predicate root                      = 1;
+}
+
+// TODO(burdon): Decide on names: Entity/Item/Object, etc.
+
+/**
+ * State snapshot.
+ */
+message ObjectSnapshot {
+  Value root                          = 1;
+}
+
+/**
+ * Atomic mutation.
+ */
+message ObjectMutation {
+  enum Operation {
+    SET                               = 0;    // Default.
+    DELETE                            = 1;
+    ARRAY_PUSH                        = 2;    // TODO(burdon): Is it possible to delete an array value (which one?)
+//  ARRAY_DELETE                      = 3;    // TODO(burdon): Identify by value.
+    SET_ADD                           = 4;    // TODO(burdon): Identify by value.
+    SET_DELETE                        = 5;
+  }
+
+  Operation operation                 = 1;
+  string key                          = 2;
+  optional Value value                = 3;
+}
+
+/**
+ * Set of mutations.
+ */
+message ObjectMutationSet {
+  repeated ObjectMutation mutations   = 1;
+}

package/src/proto/dxos/echo/model/text.proto

@@ -0,0 +1,16 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.echo.model.text;
+
+message Mutation {
+  bytes update = 1;
+  int32 client_id = 2;
+}
+
+message Snapshot {
+  bytes data = 1;
+}

package/src/proto/dxos/echo/service.proto

@@ -0,0 +1,63 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+import "dxos/echo/feed.proto";
+import "dxos/echo/snapshot.proto";
+import "dxos/echo/timeframe.proto";
+import "dxos/keys.proto";
+
+package dxos.echo.service;
+
+message SubscribeEntitySetRequest {
+  dxos.keys.PublicKey party_key = 1;
+}
+
+message SubscribeEntitySetResponse {
+  // TODO(dmaretskyi): This is wrong, the first one should use item snapshot, and deleted should be just list of ids.
+  repeated feed.EchoEnvelope added = 1;
+  repeated feed.EchoEnvelope deleted = 2;
+}
+
+message SubscribeEntityStreamRequest {
+  dxos.keys.PublicKey party_key = 1;
+  string item_id = 2;
+}
+
+message SubscribeEntityStreamResponse {
+  message Mutation {
+    message Metadata {
+     dxos.keys.PublicKey feed_key = 1;
+     dxos.keys.PublicKey member_key = 2;
+      int32 seq = 3;
+      timeframe.TimeframeVector timeframe = 4;
+    }
+
+    feed.EchoEnvelope data = 1;
+    Metadata meta = 2;
+  }
+
+  oneof kind {
+    // TODO(dmaretskyi): Move snapshot into EchoEnvelope?
+    snapshot.ItemSnapshot snapshot = 1;
+    Mutation mutation = 2;
+  }
+}
+
+message WriteRequest {
+  dxos.keys.PublicKey party_key = 1;
+  feed.EchoEnvelope mutation = 2;
+}
+
+message MutationReceipt {
+  dxos.keys.PublicKey feed_key = 1;
+  int32 seq = 2;
+}
+
+service DataService {
+  rpc SubscribeEntitySet(SubscribeEntitySetRequest) returns (stream SubscribeEntitySetResponse);
+  rpc SubscribeEntityStream(SubscribeEntityStreamRequest) returns (stream SubscribeEntityStreamResponse);
+  rpc Write(WriteRequest) returns (MutationReceipt); // TODO(burdon): Rename SubmitMutation.
+}