harmony_rust_sdk 0.8.0

Rust library to work with the Harmony chat protocol.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

syntax = "proto3";

package protocol.sync.v1;

option go_package = "github.com/harmony-development/legato/gen/sync/v1";

// Authentication data that will be sent in a `harmonytypes.v1.Token`.
message AuthData {
  // The server ID of the server initiating the transaction. For Pull,
  // this tells the server being connected to which homeservers' events it should send.
  // For Push, this tells the server being connected to which homeservers' events it is
  // receiving.
  string server_id = 1;
  // The UTC UNIX time in seconds of when the request is started. Servers should reject
  // tokens with a time too far from the current time, at their discretion. A recommended
  // variance is 1 minute.
  uint64 time = 2;
}

// Object representing a postbox event.
message Event {
  // Event sent when a user is removed from a guild.
  message UserRemovedFromGuild {
    // User ID of the user that was removed.
    uint64 user_id = 1;
    // Guild ID of the guild where the user was.
    uint64 guild_id = 2;
  }
  // Event sent when a user is added to a guild.
  message UserAddedToGuild {
    // User ID of the user that was added.
    uint64 user_id = 1;
    // Guild ID of the guild where the user will be.
    uint64 guild_id = 2;
  }
  // Event sent when a user is invited to a guild.
  message UserInvited {
    // User ID of the invitee.
    uint64 user_id = 1;
    // User ID of the user that invited.
    uint64 inviter_id = 2;
    // The invite for the guild.
    string invite_id = 3;
  }
  // Event sent when a user rejects a guild invitation.
  message UserRejectedInvite {
    // Guild ID of the guild the invitee rejected an invite for.
    uint64 guild_id = 1;
    // User ID of the invitee that rejected the invitation.
    uint64 user_id = 2;
    // Invite ID of the invite that was rejected.
    string invite_id = 3;
  }

  // The kind and data of this event.
  oneof kind {
    // User removed from a guild.
    UserRemovedFromGuild user_removed_from_guild = 1;
    // User added to a guild.
    UserAddedToGuild user_added_to_guild = 2;
    // User invited to a guild.
    UserInvited user_invited = 3;
    // User rejected a guild invitation.
    UserRejectedInvite user_rejected_invite = 4;
  }
}

// Used in `Pull` endpoint.
message PullRequest {}
// Used in `Pull` endpoint.
message PullResponse {
  // The events that were not processed yet.
  repeated Event event_queue = 1;
}

// Used in `Push` endpoint.
message PushRequest {
  // The event to push to the server.
  Event event = 1;
}
// Used in `Push` endpoint.
message PushResponse {}

// Used in `NotifyNewId` endpoint.
message NotifyNewIdRequest {
  // The new server ID of the server.
  string new_server_id = 1;
}
// Used in `NotifyNewId` endpoint.
message NotifyNewIdResponse {}

// # Postbox
//
// The postbox service forms the core of Harmony's server <-> server communications.
//
// It concerns the transfer of Events between servers, as well as ensuring reliable
// delivery of them.
//
// The semantics of events are documented in the event types. The postbox service
// is solely reliable for reliable pushing and pulling.
//
// ## Server Identification
//
// Servers are identified using their domain, and the port which they serve. This is
// called the "server ID", and must be formatted as `domain:port`. The port is NOT
// optional. Converting this ID to a URL for communicating can simply be done via
// prefixing the ID with a protocol, eg. `https://`.
//
// ## Authorisation
//
// Requests are authorised using a serialized `harmonytypes.v1.Token` in the Authorization HTTP header.
// The `data` field of the token will be a serialized `AuthData` message.
// The private key used to sign is the homeserver's private key.
//
// ## Events
//
// In this section, we will use sender and recipient to refer to the servers
// sending the events and the server receiving the events respectively.
//
// At PostboxService startup, a sender should first Pull all receivers it had
// federated from before. If a receiver makes a Push to the sender while a Pull
// is going on, the Push should be processed after the Pull is completed.
//
// The sender will attempt to Push to the receiver. If the Push RPC fails more
// than X times (a recommended retry count is 5), the event will be dispatched
// to the sender's queue for the receiver. Unless the receiver pulls these events,
// all new events should be dispatched to the queue. No new Push RPC should be made
// before the queue is emptied. This ensures that events are always received in the
// right order.
//
// It is recommended that receivers try pulling periodically, for example, every
// 1 minute after the last Push RPC by the sender. This ensures that events are recieved.
service PostboxService {
  // Endpoint to pull events.
  rpc Pull(PullRequest) returns (PullResponse) {}
  // Endpoint to push events.
  rpc Push(PushRequest) returns (PushResponse) {}
  // Endpoint to notify a server of a server ID change. It is called by the server
  // that had it's server ID changed for all servers it has federated with.
  rpc NotifyNewId(NotifyNewIdRequest) returns (NotifyNewIdResponse) {}
}