@dxos/protocols 2.28.0

package/src/proto/dxos/devtools.proto

@@ -0,0 +1,271 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.devtools;
+
+import "google/protobuf/empty.proto";
+import "google/protobuf/timestamp.proto";
+import "./echo/feed.proto";
+import "./echo/snapshot.proto";
+import "./halo/keys.proto";
+import "./halo/signed.proto";
+import "./rpc.proto";
+
+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 SubscribeToFeed(SubscribeToFeedRequest) returns (stream SubscribeToFeedResponse);
+
+  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;
+}
+
+message EnableDebugLoggingRequest {
+  string namespaces = 1;
+}
+
+message EnableDebugLoggingResponse {
+  string enabledNamespaces = 1;
+}
+
+message DisableDebugLoggingRequest {
+  string namespaces = 1;
+}
+
+message DisableDebugLoggingResponse {
+  string enabledNamespaces = 1;
+}
+
+message SubscribeToKeyringKeysRequest {}
+
+message SubscribeToKeyringKeysResponse {
+  repeated KeyRecord keys = 1;
+}
+
+message SubscribeToCredentialMessagesRequest {
+  PubKey partyKey = 1;
+}
+
+message SubscribeToCredentialMessagesResponse {
+  repeated SignedMessage messages = 1;
+}
+
+message ResetStorageRequest {}
+
+message GetNetworkPeersRequest {
+  bytes topic = 1;
+}
+
+message GetNetworkPeersResponse {
+  message PeerInfo {
+    PubKey id = 1;
+
+    // PeerState enum.
+    string state = 2;
+  
+    repeated bytes connections = 3;
+  }
+
+  repeated PeerInfo peers = 1;
+}
+
+message SubscribeToPartiesRequest {}
+
+message SubscribeToPartiesResponse {
+  message PartyInfo {
+    string key = 1;
+    bool isOpen = 2;
+    bool isActive = 3;
+    int32 feedKeys = 4;
+    map<string, string> properties = 5;
+
+    TimeframeVector timeframe = 10;
+  }
+
+  repeated PartyInfo parties = 1;
+}
+
+message SubscribeToItemsRequest {}
+
+message SubscribeToItemsResponse {
+  // JSON-encoded payload.
+  string data = 1;
+}
+
+message SubscribeToFeedsRequest {}
+
+message SubscribeToFeedsResponse {
+  message Party {
+    PubKey key = 1;
+    repeated PubKey feeds = 2;
+  }
+
+  repeated Party parties = 1;
+}
+
+message SubscribeToFeedRequest {
+  PubKey partyKey = 1;
+  PubKey feedKey = 2;
+}
+
+message SubscribeToFeedResponse {
+  message EchoFeedBlock {
+    bytes key = 1;
+    int32 seq = 2;
+    bool sync = 3;
+    string path = 4;
+    FeedMessage data = 5;
+  }
+
+  repeated EchoFeedBlock blocks = 1;
+}
+
+message GetPartySnapshotRequest {
+  required PubKey partyKey = 1;
+}
+
+message GetPartySnapshotResponse {
+  PartySnapshot snapshot = 1;
+}
+
+message SavePartySnapshotRequest {
+  required PubKey partyKey = 1;
+}
+
+message SavePartySnapshotResponse {
+  PartySnapshot snapshot = 1;
+}
+
+message ClearSnapshotsRequest {}
+
+message SubscribeToNetworkTopicsResponse {
+  message Topic {
+    PubKey topic = 1;
+    string label = 2;
+  }
+
+  repeated Topic topics = 1;
+}
+
+message SubscribeToSignalStatusResponse {
+  message SignalServer {
+    string host = 1;
+
+    // SignalApi.State enum.
+    string state = 2;
+    
+    string error = 3;
+
+    // Number of milliseconds before reconnection. 
+    // TODO(dmaretskyi): Represent as absolute timestamp.
+    int32 reconnectIn = 4;
+
+    // TODO(dmaretskyi): Change to timestamp.
+    int32 connectionStarted = 5;
+    int32 lastStateChange = 6;
+  }
+
+  repeated SignalServer servers = 1;
+}
+
+message SubscribeToSignalTraceResponse {
+  // JSON-encoded events.
+  repeated string events = 1;
+}
+
+message SubscribeToSwarmInfoRequest {}
+
+message SubscribeToSwarmInfoResponse {
+  // TODO(yivlad): Move these types to @dxos/network-manager and import them from there.
+  message SwarmInfo {
+    PubKey id = 1;
+    PubKey topic = 2;
+    string label = 3;
+    bool isActive = 4;
+    message ConnectionInfo {
+      message Json {
+        string data = 1;
+      }
+      string state = 1;
+      PubKey sessionId = 2;
+      PubKey remotePeerId = 3;
+      string transport = 4;
+      repeated string protocolExtensions = 5;
+      repeated Json events = 6;
+    }
+    repeated ConnectionInfo connections = 5;
+  }
+  repeated SwarmInfo data = 1;
+}
+
+message SetTracingOptionsRequest {
+  bool enable = 1;
+}
+
+service TracingService {
+  rpc SetTracingOptions(SetTracingOptionsRequest) returns (google.protobuf.Empty);
+  rpc SubscribeToRpcTrace (google.protobuf.Empty) returns (stream RpcMessage);
+}

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

@@ -0,0 +1,93 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+// TODO(burdon): Move Item specific to echo.item?
+package dxos.echo.feed;
+
+import "google/protobuf/any.proto";
+import "./snapshot.proto";
+
+/**
+ * Outer message type decoded by Codec.
+ * This is what is written to the feeds.
+ */
+message FeedMessage {
+  CredentialsMessage halo = 1;
+  EchoEnvelope echo = 2;
+}
+
+/**
+ * A container for dxos.credentials.Message
+ */
+message CredentialsMessage {
+  // TODO(marik-d): Use a protobuf type from credentials.
+  bytes data = 1;
+}
+
+/**
+ * Vector timestamp used to order messages.
+ */
+message TimeframeVector {
+  message Frame {
+    // TODO(marik-d): Compress using numeric feed indexes.
+    // TODO(burdon): Determine if admit DAG can be ordered. Requires party messages to be ordered (by lexical feed key).
+    bytes feedKey = 1;
+    int32 seq = 3;
+  }
+
+  repeated Frame frames = 1;
+}
+
+/**
+ * Wrapper for all ECHO messages.
+ */
+message EchoEnvelope {
+  string itemId = 1;
+  TimeframeVector timeframe = 2;
+
+  // Create item.
+  ItemGenesis genesis = 10;
+
+  // Item system mutations.
+  ItemMutation itemMutation = 11;
+
+  // Model-specific mutations.
+  bytes mutation = 12;
+
+  /// Set the model to the provided 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.
+ */
+message ItemGenesis {
+  string itemType = 1;
+  string modelType = 2;
+  string modelVersion = 3;
+  LinkData link = 4;
+}
+
+/**
+ * Item mutation.
+ */
+message ItemMutation {
+  enum Action {
+    NOOP = 0;
+    DELETE = 1;
+    RESTORE = 2;
+  }
+
+  string parentId = 1;  // TODO(burdon): Define Action type?
+  Action action = 2;
+}

package/src/proto/dxos/echo/invitation.proto

@@ -0,0 +1,29 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.echo.invitation;
+
+message InvitationDescriptor {
+  /**
+   * Defines an invitation type.
+   */
+  enum Type {
+    /// Interactive invitation is when both peers are online at the same time.
+    INTERACTIVE = 1;
+    /// Offline is when only a single peer needs to be online at the time.
+    OFFLINE = 2;
+  }
+
+  Type type = 1;
+  bytes swarmKey = 2;
+  bytes invitation = 3;
+
+  /// Only present if type == OFFLINE.
+  bytes identityKey = 4;
+
+  /// Must be stripped out when passing to another peer.
+  bytes secret = 5;
+}

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

@@ -0,0 +1,30 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.echo.metadata;
+
+import "google/protobuf/timestamp.proto";
+import "../halo/keys.proto";
+
+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;
+
+  repeated PartyMetadata parties = 2;
+
+  google.protobuf.Timestamp created = 3;
+  google.protobuf.Timestamp updated = 4;
+}
+
+message PartyMetadata {
+  PubKey key = 1;
+  repeated PubKey feedKeys = 2;
+}

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

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

package/src/proto/dxos/echo/snapshot.proto

@@ -0,0 +1,88 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.echo.snapshot;
+
+import "feed.proto";
+
+//
+// Snapshots define full party state at a given point in time.
+// They must have enough information to be able to recover the party state without reading the feed messages.
+//
+// Each snapshot is identified by a party key and a timeframe.
+// The timeframe defines the set of feed messages that have already been processed.
+// When loading from the snapshot, application would skip all of the feed messages up to (and including) the provided timeframe.
+//
+
+message PartySnapshot {
+  bytes partyKey = 1;
+  TimeframeVector timeframe = 2;
+
+  // Unix timestamp of the snapshot creation time. For information purposes only.
+  int32 timestamp = 3;
+
+  HaloStateSnapshot halo = 11;
+  // TODO(dmaretskyi): Rename to EchoSnapshot.
+  DatabaseSnapshot database = 12;
+}
+
+message DatabaseSnapshot {
+  repeated ItemSnapshot items = 1;
+}
+
+// TODO(dmaretskyi): Rename to HaloSnapshot.
+// For now we just store and replay a list of all halo messages as thier number is expected to be relatively low.
+message HaloStateSnapshot {
+  repeated dxos.CredentialsMessage messages = 1;
+}
+
+message ItemSnapshot {
+  string itemId = 1;
+
+  string itemType = 2;
+  string modelType = 3;
+  string modelVersion = 4;
+
+  string parentId = 5;
+
+  // TODO(burdon): = 10 (make room for other meta?)
+  ModelSnapshot model = 6;
+}
+
+/**
+ * Represents the reified state of a state machine.
+ * The snapshots make consist of a custom snapshot object and/or a list of mutations
+ * that are applied to the snapshot or the initial state.
+ */
+message ModelSnapshot {
+  /**
+   * Encoded model snapshot (defined by the model's codec).
+   * If undefined the state machine will be initialized with it's default state.
+   */
+  optional bytes snapshot = 1;
+
+  /**
+   * Mutations to be applied on top of the snapshot, or on top of initial state if the snapshot is undefined.
+   */
+  repeated ModelMutation mutations = 2;
+}
+
+message ModelMutation {
+  // TODO(burdon): Remove required.
+  // Encoded model mutation, format is defined by model's codec.
+  required bytes mutation = 1;
+  required ModelMutationMeta meta = 2;
+}
+
+message ModelMutationMeta {
+  // TODO(burdon): Remove required.
+  required bytes feedKey = 1;
+  required int32 seq = 2;
+  required bytes memberKey = 3;
+}
+
+
+

package/src/proto/dxos/halo/auth.proto

@@ -0,0 +1,20 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.credentials.auth;
+
+import "keys.proto";
+import "signed.proto";
+
+/**
+ * The payload for a SignedMessage sent during handshake for replication authentication.
+ */
+message Auth {
+  PubKey partyKey = 1;     // The publicKey of the target Party for these credentials.
+  PubKey deviceKey = 2;    // The publicKey of the authenticating Device.
+  PubKey identityKey = 3;  // The publicKey of the authenticating Identity.
+  PubKey feedKey = 4;      // The publicKey of the authenticating Identity.
+}