anil.recoil.org
Matrix protocol in OCaml, Eio specialised
1(** Sync operations and long-polling loop. *)
2
3(** {1 Sync API} *)
4
5(** Sync parameters. *)
6type params = {
7 filter : string option;
8 (** Filter ID to use (from {!create_filter}). *)
9 since : string option;
10 (** Sync token from previous sync. *)
11 full_state : bool;
12 (** If true, return full state even if since is provided. *)
13 set_presence : [ `Online | `Offline | `Unavailable ] option;
14 (** Presence state to set. *)
15 timeout : int;
16 (** Long-poll timeout in milliseconds. 0 for immediate return. *)
17}
18
19(** Default sync parameters: 30 second timeout, no filter. *)
20val default_params : params
21
22(** Perform a single sync request.
23
24 Returns the sync response from the server. The [next_batch] field
25 should be used as [since] for the next sync request. *)
26val sync :
27 Client.t ->
28 ?params:params ->
29 unit ->
30 (Matrix_proto.Sync.Response.t, Error.t) result
31
32(** {1 Sync Loop} *)
33
34(** Action to take after processing a sync response or error. *)
35type action =
36 | Continue (** Continue syncing *)
37 | Stop (** Stop the sync loop *)
38 | Retry_after of int (** Retry after N milliseconds *)
39
40(** Callbacks for the sync loop. *)
41type callbacks = {
42 on_sync : Matrix_proto.Sync.Response.t -> action;
43 (** Called for each successful sync response. *)
44 on_error : Error.t -> action;
45 (** Called when sync fails. *)
46}
47
48(** Run a continuous sync loop.
49
50 This function blocks and continuously syncs with the server,
51 calling the appropriate callback for each response or error.
52 The loop continues until a callback returns [Stop].
53
54 @param clock Eio clock for sleeping on Retry_after.
55 @param initial_since Starting sync token (None for initial sync).
56 @param params Sync parameters to use (timeout, filter, etc.). *)
57val sync_forever :
58 Client.t ->
59 clock:_ Eio.Time.clock ->
60 ?initial_since:string ->
61 ?params:params ->
62 callbacks:callbacks ->
63 unit ->
64 unit
65
66(** {1 Filters} *)
67
68(** Event filter for sync. *)
69type event_filter = {
70 limit : int option;
71 not_senders : string list;
72 not_types : string list;
73 senders : string list;
74 types : string list;
75}
76
77(** Room event filter. *)
78type room_event_filter = {
79 limit : int option;
80 not_senders : string list;
81 not_types : string list;
82 senders : string list;
83 types : string list;
84 lazy_load_members : bool;
85 include_redundant_members : bool;
86 not_rooms : string list;
87 rooms : string list;
88 contains_url : bool option;
89}
90
91(** Room filter. *)
92type room_filter = {
93 not_rooms : string list;
94 rooms : string list;
95 ephemeral : room_event_filter option;
96 include_leave : bool;
97 state : room_event_filter option;
98 timeline : room_event_filter option;
99 account_data : room_event_filter option;
100}
101
102(** Complete sync filter. *)
103type filter = {
104 event_fields : string list;
105 event_format : [ `Client | `Federation ];
106 presence : event_filter option;
107 account_data : event_filter option;
108 room : room_filter option;
109}
110
111(** Default empty event filter. *)
112val default_event_filter : event_filter
113
114(** Default room event filter with lazy loading enabled. *)
115val default_room_event_filter : room_event_filter
116
117(** Default room filter. *)
118val default_room_filter : room_filter
119
120(** Default filter. *)
121val default_filter : filter
122
123(** Create a filter on the homeserver.
124
125 Returns the filter ID that can be used in sync requests. *)
126val create_filter :
127 Client.t ->
128 filter:filter ->
129 (string, Error.t) result
130
131(** Get an existing filter from the homeserver. *)
132val get_filter :
133 Client.t ->
134 filter_id:string ->
135 (filter, Error.t) result