@workerstack/clients 1.0.0-rc.28 → 1.0.0-rc.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/README.md +30 -7
  2. package/dist/emit/cli/commands.js +25 -5
  3. package/dist/emit/cli/flags.js +7 -3
  4. package/dist/emit/cli/skills.js +5 -1
  5. package/dist/emit/csharp/realtime.d.ts +1 -8
  6. package/dist/emit/csharp/realtime.js +25 -25
  7. package/dist/emit/csharp/sdk-answer.d.ts +10 -2
  8. package/dist/emit/csharp/sdk-method.js +9 -2
  9. package/dist/emit/csharp/sse.d.ts +0 -11
  10. package/dist/emit/csharp/sse.js +91 -10
  11. package/dist/emit/csharp/transport.js +3 -3
  12. package/dist/emit/csharp/types-messages.d.ts +47 -0
  13. package/dist/emit/csharp/types-messages.js +172 -0
  14. package/dist/emit/csharp/types-names.js +3 -2
  15. package/dist/emit/csharp/ws.d.ts +0 -15
  16. package/dist/emit/csharp/ws.js +26 -5
  17. package/dist/emit/go/sdk-answer.d.ts +24 -1
  18. package/dist/emit/go/sdk-method.d.ts +3 -0
  19. package/dist/emit/go/sdk-method.js +16 -10
  20. package/dist/emit/go/sse.d.ts +2 -10
  21. package/dist/emit/go/sse.js +87 -12
  22. package/dist/emit/go/types-union.d.ts +3 -2
  23. package/dist/emit/go/types-union.js +2 -0
  24. package/dist/emit/go/types.d.ts +6 -0
  25. package/dist/emit/go/types.js +12 -1
  26. package/dist/emit/go/ws.d.ts +4 -11
  27. package/dist/emit/go/ws.js +214 -58
  28. package/dist/emit/java/json.d.ts +3 -0
  29. package/dist/emit/java/layout-ast.d.ts +4 -1
  30. package/dist/emit/java/layout-types.js +1 -1
  31. package/dist/emit/java/models-names.d.ts +2 -0
  32. package/dist/emit/java/models-names.js +1 -0
  33. package/dist/emit/java/models-union.d.ts +12 -1
  34. package/dist/emit/java/models-union.js +11 -5
  35. package/dist/emit/java/models.d.ts +5 -0
  36. package/dist/emit/java/models.js +22 -7
  37. package/dist/emit/java/realtime.d.ts +29 -9
  38. package/dist/emit/java/realtime.js +45 -10
  39. package/dist/emit/java/sdk-mirror.js +6 -5
  40. package/dist/emit/java/sdk-op.js +1 -1
  41. package/dist/emit/java/sse.d.ts +11 -10
  42. package/dist/emit/java/sse.js +104 -5
  43. package/dist/emit/java/ws.d.ts +46 -7
  44. package/dist/emit/java/ws.js +89 -4
  45. package/dist/emit/mcp/output-schema.d.ts +4 -2
  46. package/dist/emit/mcp/output-schema.js +56 -12
  47. package/dist/emit/python/realtime.d.ts +9 -6
  48. package/dist/emit/python/realtime.js +21 -19
  49. package/dist/emit/python/sdk-answer.d.ts +5 -1
  50. package/dist/emit/python/sdk-method.d.ts +1 -1
  51. package/dist/emit/python/sdk-method.js +33 -6
  52. package/dist/emit/python/sdk.js +22 -2
  53. package/dist/emit/python/sse.d.ts +0 -5
  54. package/dist/emit/python/sse.js +35 -5
  55. package/dist/emit/python/types.d.ts +7 -0
  56. package/dist/emit/python/types.js +20 -3
  57. package/dist/emit/python/ws.d.ts +20 -6
  58. package/dist/emit/python/ws.js +67 -1
  59. package/dist/emit/rust/realtime.d.ts +7 -5
  60. package/dist/emit/rust/realtime.js +14 -17
  61. package/dist/emit/rust/sdk-method.js +1 -1
  62. package/dist/emit/rust/sse.d.ts +11 -7
  63. package/dist/emit/rust/sse.js +52 -6
  64. package/dist/emit/rust/types-union.d.ts +9 -1
  65. package/dist/emit/rust/types-union.js +4 -0
  66. package/dist/emit/rust/types.d.ts +9 -0
  67. package/dist/emit/rust/types.js +13 -7
  68. package/dist/emit/rust/ws.d.ts +22 -4
  69. package/dist/emit/rust/ws.js +57 -7
  70. package/dist/emit/ts/sdk-types-preamble.js +4 -0
  71. package/dist/emit/ts/sdk-types.js +49 -10
  72. package/dist/emit/ts/sdk.js +2 -2
  73. package/dist/emit/ts/service-map.d.ts +8 -2
  74. package/dist/emit/ts/service-map.js +30 -2
  75. package/dist/emit/ts/type-gen.js +6 -4
  76. package/dist/ir/build.js +4 -0
  77. package/dist/ir/model.d.ts +14 -0
  78. package/dist/ir/sdk-model.d.ts +25 -1
  79. package/dist/ir/sdk-model.js +35 -5
  80. package/dist/ir/slots.d.ts +1 -1
  81. package/dist/ir/slots.js +9 -3
  82. package/dist/ir/streams.d.ts +16 -0
  83. package/dist/ir/streams.js +40 -0
  84. package/dist/runtime/cli/socket.go +107 -13
  85. package/dist/runtime/cli/stream.go +18 -11
  86. package/dist/runtime/csharp/Adapters.cs +12 -11
  87. package/dist/runtime/csharp/Events.cs +22 -17
  88. package/dist/runtime/csharp/Realtime.cs +50 -23
  89. package/dist/runtime/csharp/RealtimeLoop.cs +1 -1
  90. package/dist/runtime/csharp/TransportSse.cs +3 -3
  91. package/dist/runtime/csharp/Ws.cs +1 -1
  92. package/dist/runtime/csharp/WsDial.cs +19 -1
  93. package/dist/runtime/csharp/WsTyped.cs +109 -0
  94. package/dist/runtime/go/realtime.go +125 -41
  95. package/dist/runtime/go/realtime_loop.go +21 -18
  96. package/dist/runtime/go/result.go +2 -1
  97. package/dist/runtime/go/sse.go +11 -0
  98. package/dist/runtime/go/stream.go +29 -13
  99. package/dist/runtime/go/transport.go +15 -21
  100. package/dist/runtime/go/transport_longpoll.go +3 -4
  101. package/dist/runtime/go/transport_sse.go +6 -6
  102. package/dist/runtime/go/ws.go +157 -61
  103. package/dist/runtime/java/EventStream.java +47 -29
  104. package/dist/runtime/java/Exchange.java +5 -5
  105. package/dist/runtime/java/Flight.java +3 -3
  106. package/dist/runtime/java/Realtime.java +45 -11
  107. package/dist/runtime/java/ResumableConnection.java +77 -32
  108. package/dist/runtime/java/Socket.java +8 -4
  109. package/dist/runtime/java/SseAdapter.java +1 -1
  110. package/dist/runtime/java/TypedWebSocket.java +81 -24
  111. package/dist/runtime/java/WsAdapter.java +4 -2
  112. package/dist/runtime/java/WsDial.java +12 -5
  113. package/dist/runtime/python/events.py +25 -11
  114. package/dist/runtime/python/operation.py +6 -1
  115. package/dist/runtime/python/realtime.py +47 -33
  116. package/dist/runtime/python/send_async.py +1 -0
  117. package/dist/runtime/python/transport_sse.py +2 -2
  118. package/dist/runtime/python/transport_ws.py +1 -1
  119. package/dist/runtime/python/ws.py +100 -39
  120. package/dist/runtime/rust/events.rs +64 -41
  121. package/dist/runtime/rust/realtime.rs +80 -34
  122. package/dist/runtime/rust/realtime_loop.rs +37 -12
  123. package/dist/runtime/rust/sse.rs +3 -2
  124. package/dist/runtime/rust/transport_sse.rs +1 -1
  125. package/dist/runtime/rust/transport_ws.rs +3 -2
  126. package/dist/runtime/rust/ws.rs +122 -50
  127. package/dist/runtime/ts/realtime-connection.ts +22 -0
  128. package/dist/runtime/ts/realtime-transports.ts +13 -4
  129. package/dist/runtime/ts/realtime.ts +27 -3
  130. package/dist/runtime/ts/sdk-realtime.ts +1 -1
  131. package/dist/runtime/ts/sdk-sse.ts +31 -14
  132. package/dist/runtime/ts/sdk-ws.ts +2 -1
  133. package/dist/runtime/ts/sdk.ts +9 -2
  134. package/dist/runtime/ts/sse.ts +8 -0
  135. package/dist/runtime/ts/ws.ts +88 -50
  136. package/package.json +3 -34
@@ -5,42 +5,136 @@ package cli
5
5
  import (
6
6
  "bufio"
7
7
  "context"
8
+ "encoding/json"
8
9
  "errors"
10
+ "fmt"
11
+ "sort"
12
+ "strconv"
13
+ "strings"
14
+ "sync/atomic"
9
15
 
10
16
  "github.com/coder/websocket"
11
17
  )
12
18
 
13
- // Socket is a WebSocket connection as the SDK opens it.
19
+ // Socket is a WebSocket connection as the SDK opens it, whatever its messages' types.
14
20
  type Socket interface {
15
- Send(ctx context.Context, data any) error
16
- Read(ctx context.Context) ([]byte, error)
21
+ SendText(ctx context.Context, text string) error
17
22
  Close(code websocket.StatusCode, reason string) error
18
23
  }
19
24
 
25
+ // LineCheck refuses an input line that is no message the server receives.
26
+ type LineCheck func(line string) error
27
+
28
+ // JSONLine checks that a line decodes as T and holds each field of required.
29
+ func JSONLine[T any](required ...string) LineCheck {
30
+ return func(line string) error {
31
+ var msg T
32
+ if err := json.Unmarshal([]byte(line), &msg); err != nil {
33
+ var syntax *json.SyntaxError
34
+ if errors.As(err, &syntax) {
35
+ return fmt.Errorf("not valid JSON: %w", err)
36
+ }
37
+ return err
38
+ }
39
+ var fields map[string]json.RawMessage
40
+ _ = json.Unmarshal([]byte(line), &fields) // T decoded: a missing field is all left to find
41
+ for _, name := range required {
42
+ if _, ok := fields[name]; !ok {
43
+ return fmt.Errorf("missing %q", name)
44
+ }
45
+ }
46
+ return nil
47
+ }
48
+ }
49
+
50
+ // Keyed checks a line by the member its key names, one of members.
51
+ func Keyed(key string, members map[string]LineCheck) LineCheck {
52
+ values := make([]string, 0, len(members))
53
+ for value := range members {
54
+ values = append(values, strconv.Quote(value))
55
+ }
56
+ sort.Strings(values)
57
+ want := fmt.Errorf("want an object whose %q is one of %s", key, strings.Join(values, ", "))
58
+ return func(line string) error {
59
+ var fields map[string]json.RawMessage
60
+ if err := json.Unmarshal([]byte(line), &fields); err != nil {
61
+ var syntax *json.SyntaxError
62
+ if errors.As(err, &syntax) {
63
+ return fmt.Errorf("not valid JSON: %w", err)
64
+ }
65
+ return want
66
+ }
67
+ var value string
68
+ _ = json.Unmarshal(fields[key], &value) // no string there: no member's value
69
+ if check, ok := members[value]; ok {
70
+ return check(line)
71
+ }
72
+ return want
73
+ }
74
+ }
75
+
76
+ // checked is check's verdict on line; none without a check.
77
+ func checked(check LineCheck, line string) error {
78
+ if check == nil {
79
+ return nil
80
+ }
81
+ return check(line)
82
+ }
83
+
84
+ // Undecoded reports whether err is an E, the SDK's error for a message that does not decode.
85
+ func Undecoded[E error](err error) bool {
86
+ var undecoded E
87
+ return errors.As(err, &undecoded)
88
+ }
89
+
20
90
  // Converse sends each standard-input line as a text frame, reading on after its end, and prints
21
- // each message as one line until the server closes, --take is met (a close frame 1000) or the run
22
- // is interrupted (a close frame 1000 "interrupted").
23
- func (s *Stream) Converse(conn Socket) error {
91
+ // each message read returns as one line (a typed one as its JSON) until the server closes, --take
92
+ // is met (a close frame 1000) or the run is interrupted (a close frame 1000 "interrupted"). With a
93
+ // check, a blank line is skipped and a line it refuses is not sent: the refusal goes to stderr as
94
+ // an error does, the run reads on, and its end is a usage error counting the lines not sent. A
95
+ // message that does not decode, as undecoded tells, ends the run with its error after a close
96
+ // frame 1007.
97
+ func Converse[T any](s *Stream, conn Socket, read func(context.Context) (T, error), check LineCheck, undecoded func(error) bool) error {
24
98
  /* reads outlive Ctrl-C, so the close frame goes out and is answered */
25
99
  ctx := context.WithoutCancel(s.c.Context())
26
100
  stop := context.AfterFunc(s.c.Context(), func() { conn.Close(websocket.StatusNormalClosure, "interrupted") })
27
101
  defer stop()
102
+ var refused atomic.Int64
28
103
  go func() {
29
104
  lines := bufio.NewScanner(s.c.InOrStdin())
30
- for lines.Scan() {
31
- if conn.Send(ctx, lines.Text()) != nil {
105
+ for n := 1; lines.Scan(); n++ {
106
+ line := lines.Text()
107
+ if check != nil && strings.TrimSpace(line) == "" {
108
+ continue
109
+ }
110
+ if err := checked(check, line); err != nil {
111
+ refused.Add(1)
112
+ report(s.c, Usage("input line %d not sent: %v", n, err), false)
113
+ continue
114
+ }
115
+ if conn.SendText(ctx, line) != nil {
32
116
  return
33
117
  }
34
118
  }
35
119
  }()
120
+ ended := func(err error) error {
121
+ if n := refused.Load(); err == nil && n > 0 && s.c.Context().Err() == nil {
122
+ return Usage("input lines not sent: %d", n)
123
+ }
124
+ return err
125
+ }
36
126
  for {
37
- message, err := conn.Read(ctx)
38
- if err != nil {
39
- return closedOf(err, s.c.Context().Err() != nil)
127
+ message, err := read(ctx)
128
+ switch {
129
+ case err != nil && undecoded(err):
130
+ conn.Close(websocket.StatusInvalidFramePayloadData, "a message did not decode")
131
+ return err
132
+ case err != nil:
133
+ return ended(closedOf(err, s.c.Context().Err() != nil))
40
134
  }
41
- if !s.Write(textOf(message)) {
135
+ if !s.Write(printed(message)) {
42
136
  conn.Close(websocket.StatusNormalClosure, "")
43
- return s.err
137
+ return ended(s.err)
44
138
  }
45
139
  }
46
140
  }
@@ -149,38 +149,45 @@ func (e *Closed) Error() string {
149
149
  return fmt.Sprintf("the server closed the connection: %d %s", e.Code, e.Reason)
150
150
  }
151
151
 
152
- // Feed is a realtime connection as the SDK opens it.
152
+ // Feed is a realtime connection as the SDK opens it, whatever its messages' types.
153
153
  type Feed interface {
154
- Events() <-chan any
155
154
  Errors() <-chan error
156
155
  Cursor() (lastEventID, reconnectToken string)
157
156
  Close() error
158
157
  }
159
158
 
160
- // Resume prints each event a realtime feed delivers until it ends, --take is met or the run is
159
+ // Resume prints each message of events, the feed's, until it ends, --take is met or the run is
161
160
  // interrupted; then its cursor, to resume from.
162
- func (s *Stream) Resume(feed Feed) error {
163
- err := s.follow(feed)
161
+ func Resume[T any](s *Stream, feed Feed, events <-chan T) error {
162
+ err := follow(s, feed, events)
164
163
  feed.Close()
165
164
  s.Cursor(feed.Cursor())
166
165
  return err
167
166
  }
168
167
 
169
- func (s *Stream) follow(feed Feed) error {
168
+ // printed is a message as the CLI prints it: bytes or a string as text, any other value as JSON.
169
+ func printed(message any) any {
170
+ switch v := message.(type) {
171
+ case []byte:
172
+ return textOf(v)
173
+ case string:
174
+ return textOf([]byte(v))
175
+ }
176
+ return message
177
+ }
178
+
179
+ func follow[T any](s *Stream, feed Feed, events <-chan T) error {
170
180
  for {
171
181
  select {
172
182
  case <-s.c.Context().Done():
173
183
  return nil
174
184
  case err := <-feed.Errors():
175
185
  return err
176
- case v, ok := <-feed.Events():
186
+ case v, ok := <-events:
177
187
  if !ok {
178
188
  return nil
179
189
  }
180
- if text, isText := v.(string); isText {
181
- v = textOf([]byte(text))
182
- }
183
- if !s.Write(v) {
190
+ if !s.Write(printed(v)) {
184
191
  return s.err
185
192
  }
186
193
  }
@@ -40,15 +40,8 @@ public sealed class TransportOptions
40
40
  /// <summary>The first reconnect's base delay, doubled per attempt up to 30 s; an SSE <c>retry</c> replaces it.</summary>
41
41
  public TimeSpan ReconnectDelay { get; init; } = TimeSpan.FromSeconds(1);
42
42
 
43
- internal static TransportOptions Of(string? lastEventId, string? reconnectToken, IReadOnlyList<string>? protocols, int? maxReconnectAttempts, TimeSpan? reconnectDelay) =>
44
- new()
45
- {
46
- LastEventId = lastEventId,
47
- ReconnectToken = reconnectToken,
48
- Protocols = protocols ?? [],
49
- MaxReconnectAttempts = maxReconnectAttempts ?? 5,
50
- ReconnectDelay = reconnectDelay ?? TimeSpan.FromSeconds(1),
51
- };
43
+ /* the connection's own copy: it advances the cursor, never the caller's value */
44
+ internal TransportOptions Copy() => (TransportOptions)MemberwiseClone();
52
45
 
53
46
  /* past a message: its SSE id, else the payload's id or last_event_id (a string or an integer), and its reconnect_token */
54
47
  internal void Advance(string? id, JsonElement payload)
@@ -162,12 +155,20 @@ internal sealed class Dial(Transport client, Operation op, Call call)
162
155
 
163
156
  internal sealed partial class Transport
164
157
  {
165
- public async Task<ResumableConnection<T>> RealtimeAsync<T>(Operation op, Call call, TransportOptions options, JsonTypeInfo<T> info, CancellationToken cancellationToken)
158
+ /* a connection whose operation declares no messages: a message that is no JSON reads as a JSON string */
159
+ public Task<ResumableConnection<TIn, TOut>> RealtimeAsync<TIn, TOut>(Operation op, Call call, TransportOptions options, JsonTypeInfo<TIn> read, JsonTypeInfo<TOut> write, CancellationToken cancellationToken) =>
160
+ OpenRealtimeAsync(op, call, options, read, write, false, cancellationToken);
161
+
162
+ /* a connection whose operation declares its messages: a message that is no JSON throws */
163
+ public Task<ResumableConnection<TIn, TOut>> TypedRealtimeAsync<TIn, TOut>(Operation op, Call call, TransportOptions options, JsonTypeInfo<TIn> read, JsonTypeInfo<TOut> write, CancellationToken cancellationToken) =>
164
+ OpenRealtimeAsync(op, call, options, read, write, true, cancellationToken);
165
+
166
+ private async Task<ResumableConnection<TIn, TOut>> OpenRealtimeAsync<TIn, TOut>(Operation op, Call call, TransportOptions options, JsonTypeInfo<TIn> read, JsonTypeInfo<TOut> write, bool strict, CancellationToken cancellationToken)
166
167
  {
167
168
  var dial = new Dial(this, op, call);
168
169
  var url = dial.Url();
169
170
  cancellationToken.ThrowIfCancellationRequested();
170
- var connection = new ResumableConnection<T>(url.ToString(), [new WsAdapter(dial), new SseAdapter(dial), new LongPollAdapter(dial)], info, options);
171
+ var connection = new ResumableConnection<TIn, TOut>(url.ToString(), [new WsAdapter(dial), new SseAdapter(dial), new LongPollAdapter(dial)], read, write, options) { Strict = strict };
171
172
  using var bound = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
172
173
  bound.CancelAfter(RealtimeLoop.OpenLimit);
173
174
  try
@@ -10,21 +10,22 @@ using System.Threading.Tasks;
10
10
 
11
11
  namespace Http.Runtime;
12
12
 
13
- /// <summary>One server-sent event: its decoded data, its type, the stream's last event id when it came, and its <c>retry</c>.</summary>
13
+ /// <summary>One server-sent event: its data, its type, the stream's last event id when it came, and its <c>retry</c>.</summary>
14
14
  public sealed record SseEvent<T>(T Data, string? Event, string? Id, TimeSpan? Retry);
15
15
 
16
16
  /// <summary>
17
- /// An open event stream, read once by <c>await foreach</c>. No timeout bounds it. An event that does not decode, a
18
- /// cap or a failed read is thrown once and ends it. The method's token or the read's own token ends it with an
17
+ /// An open event stream, read once by <c>await foreach</c>, each event decoded whole into <typeparamref name="TEvent"/>:
18
+ /// an <see cref="SseEvent{T}"/>, or a named-event operation's own record. No timeout bounds it. An event that does not
19
+ /// decode, a cap or a failed read is thrown once and ends it. The method's token or the read's own token ends it with an
19
20
  /// OperationCanceledException; leaving the loop or <see cref="DisposeAsync"/> ends it quietly. Each end lets the
20
21
  /// connection go: dispose it, or read it to its end.
21
22
  /// </summary>
22
- public sealed class EventStream<T> : IAsyncEnumerable<SseEvent<T>>, IAsyncDisposable
23
+ public sealed class EventStream<TEvent> : IAsyncEnumerable<TEvent>, IAsyncDisposable
23
24
  {
24
25
  private const int ReadBuffer = 65_536;
25
26
 
26
27
  private readonly HttpResponseMessage _response;
27
- private readonly Func<string, T> _decode;
28
+ private readonly Func<SseEvent<string>, TEvent> _decode;
28
29
  private readonly CancellationToken _call;
29
30
  private readonly CancellationTokenSource _end = new();
30
31
  private readonly CancellationTokenRegistration _registration;
@@ -36,19 +37,19 @@ public sealed class EventStream<T> : IAsyncEnumerable<SseEvent<T>>, IAsyncDispos
36
37
  private int _taken;
37
38
  private int _released;
38
39
 
39
- internal EventStream(HttpResponseMessage response, Func<string, T> decode, CancellationToken call)
40
+ internal EventStream(HttpResponseMessage response, Func<SseEvent<string>, TEvent> decode, CancellationToken call)
40
41
  {
41
42
  _response = response;
42
43
  _decode = decode;
43
44
  _call = call;
44
- _registration = call.Register(static stream => ((EventStream<T>)stream!).Release(), this);
45
+ _registration = call.Register(static stream => ((EventStream<TEvent>)stream!).Release(), this);
45
46
  }
46
47
 
47
- /// <summary>The id of the last event read, to resume from; empty before any.</summary>
48
+ /// <summary>The id of the last event read, to resume from, taken before the event decodes; empty before any.</summary>
48
49
  public string LastEventId { get; private set; } = "";
49
50
 
50
51
  /// <summary>The stream's events in order; a second enumeration throws InvalidOperationException.</summary>
51
- public IAsyncEnumerator<SseEvent<T>> GetAsyncEnumerator(CancellationToken cancellationToken = default) =>
52
+ public IAsyncEnumerator<TEvent> GetAsyncEnumerator(CancellationToken cancellationToken = default) =>
52
53
  Interlocked.Exchange(ref _taken, 1) == 0
53
54
  ? EventsAsync(cancellationToken)
54
55
  : throw new InvalidOperationException("an EventStream is read once");
@@ -71,7 +72,7 @@ public sealed class EventStream<T> : IAsyncEnumerable<SseEvent<T>>, IAsyncDispos
71
72
  }
72
73
  }
73
74
 
74
- private async IAsyncEnumerator<SseEvent<T>> EventsAsync(CancellationToken token)
75
+ private async IAsyncEnumerator<TEvent> EventsAsync(CancellationToken token)
75
76
  {
76
77
  using var read = CancellationTokenSource.CreateLinkedTokenSource(token, _end.Token);
77
78
  try
@@ -81,9 +82,8 @@ public sealed class EventStream<T> : IAsyncEnumerable<SseEvent<T>>, IAsyncDispos
81
82
  var cap = await PullAsync(token, read.Token).ConfigureAwait(false);
82
83
  foreach (var raw in _pending)
83
84
  {
84
- var data = _decode(raw.Data);
85
85
  LastEventId = raw.Id ?? "";
86
- yield return new SseEvent<T>(data, raw.Event, raw.Id, raw.Retry);
86
+ yield return _decode(new SseEvent<string>(raw.Data, raw.Event, raw.Id, raw.Retry));
87
87
  }
88
88
  _pending.Clear();
89
89
  if (cap is not null)
@@ -132,16 +132,21 @@ public sealed class EventStream<T> : IAsyncEnumerable<SseEvent<T>>, IAsyncDispos
132
132
 
133
133
  internal sealed partial class Transport
134
134
  {
135
- public async Task<EventStream<T>> EventsAsync<T>(Operation op, Call call, string? lastEventId, JsonTypeInfo<T> info, CancellationToken cancellationToken) =>
136
- new(await OpenedAsync(op, call, lastEventId, cancellationToken).ConfigureAwait(false), data => Event(data, info), cancellationToken);
135
+ public async Task<EventStream<SseEvent<T>>> EventsAsync<T>(Operation op, Call call, string? lastEventId, JsonTypeInfo<T> info, CancellationToken cancellationToken) =>
136
+ new(await OpenedAsync(op, call, lastEventId, cancellationToken).ConfigureAwait(false), e => new(EventData(e.Data, info), e.Event, e.Id, e.Retry), cancellationToken);
137
137
 
138
- public async Task<EventStream<string>> TextEventsAsync(Operation op, Call call, string? lastEventId, CancellationToken cancellationToken) =>
139
- new(await OpenedAsync(op, call, lastEventId, cancellationToken).ConfigureAwait(false), data => data, cancellationToken);
138
+ public async Task<EventStream<SseEvent<string>>> TextEventsAsync(Operation op, Call call, string? lastEventId, CancellationToken cancellationToken) =>
139
+ new(await OpenedAsync(op, call, lastEventId, cancellationToken).ConfigureAwait(false), e => e, cancellationToken);
140
+
141
+ /* a named-event operation's events, each decoded by its name through the context's options */
142
+ public async Task<EventStream<TEvent>> NamedEventsAsync<TEvent>(Operation op, Call call, string? lastEventId, Func<SseEvent<string>, JsonSerializerOptions, TEvent> named, CancellationToken cancellationToken) =>
143
+ new(await OpenedAsync(op, call, lastEventId, cancellationToken).ConfigureAwait(false), e => named(e, Json), cancellationToken);
140
144
 
141
145
  private Task<HttpResponseMessage> OpenedAsync(Operation op, Call call, string? lastEventId, CancellationToken cancellationToken) =>
142
146
  new Exchange(this, op, call with { Headers = [.. call.Headers, Arg.Text("Last-Event-ID", lastEventId)] }, stream: true).OpenAsync(cancellationToken);
143
147
 
144
- private static T Event<T>(string data, JsonTypeInfo<T> info)
148
+ /// <summary>An event's data decoded into <typeparamref name="T"/>; a misfit or null is a <see cref="DecodeException"/>.</summary>
149
+ internal static T EventData<T>(string data, JsonTypeInfo<T> info)
145
150
  {
146
151
  try
147
152
  {
@@ -23,24 +23,33 @@ public enum ConnectionState
23
23
 
24
24
  /// <summary>
25
25
  /// A connection over a chain of transports, tried in order, read by <c>await foreach</c>: each message decoded as
26
- /// <typeparamref name="T"/> (a message that does not decode throws once, the connection kept), the cursor in
27
- /// <see cref="Options"/> advanced past it. After a drop it reopens the chain from the cursor, backing off from the
28
- /// delay (an SSE <c>retry</c> first), doubling to 30 s, for up to <c>MaxReconnectAttempts</c> in a row; giving up
29
- /// throws the last failure once, and the enumeration then ends. Leaving a loop keeps the connection; a canceled read
30
- /// leaves it reconnecting. <see cref="CloseAsync"/> from any task ends a pending read with no message.
26
+ /// <typeparamref name="TIn"/>, what the server sends, the cursor in <see cref="Options"/> advanced past it first, and
27
+ /// <see cref="Message"/> fired before it is yielded; <see cref="SendAsync(TOut, CancellationToken)"/> sends the JSON
28
+ /// of a <typeparamref name="TOut"/>, what the server receives. A message that does not decode throws
29
+ /// <see cref="DecodeException"/> once and ends that enumeration, the connection kept, and a new <c>await foreach</c>
30
+ /// reads the next one; a connection of declared messages reads only JSON, any other reads a message that is no JSON
31
+ /// as a JSON string. After a drop it reopens the chain from the cursor, backing off from the delay (an SSE
32
+ /// <c>retry</c> first), doubling to 30 s, for up to <c>MaxReconnectAttempts</c> in a row; giving up throws the last
33
+ /// failure once, and the enumeration then ends. Leaving a loop keeps the connection; a canceled read leaves it
34
+ /// reconnecting. <see cref="CloseAsync"/> from any task ends a pending read with no message.
31
35
  /// </summary>
32
- public sealed class ResumableConnection<T> : IAsyncEnumerable<T>, IAsyncDisposable
36
+ public sealed class ResumableConnection<TIn, TOut> : IAsyncEnumerable<TIn>, IAsyncDisposable
33
37
  {
34
- private readonly JsonTypeInfo<T> _info;
38
+ private readonly JsonTypeInfo<TIn> _read;
39
+ private readonly JsonTypeInfo<TOut> _write;
35
40
  private readonly RealtimeLoop _loop;
36
41
 
37
- /// <summary>A connection to <paramref name="url"/> over <paramref name="adapters"/>, its messages read through <paramref name="info"/>; it opens at <see cref="ConnectAsync"/>.</summary>
38
- public ResumableConnection(string url, IReadOnlyList<ITransportAdapter> adapters, JsonTypeInfo<T> info, TransportOptions? options = null)
42
+ /// <summary>
43
+ /// A connection to <paramref name="url"/> over <paramref name="adapters"/>, its messages read through
44
+ /// <paramref name="read"/> and sent through <paramref name="write"/>; it opens at <see cref="ConnectAsync"/>.
45
+ /// </summary>
46
+ public ResumableConnection(string url, IReadOnlyList<ITransportAdapter> adapters, JsonTypeInfo<TIn> read, JsonTypeInfo<TOut> write, TransportOptions? options = null)
39
47
  {
40
48
  Url = url;
41
49
  Adapters = adapters;
42
50
  Options = options ?? new TransportOptions();
43
- _info = info;
51
+ _read = read;
52
+ _write = write;
44
53
  _loop = new RealtimeLoop(adapters, Options, url);
45
54
  }
46
55
 
@@ -59,60 +68,78 @@ public sealed class ResumableConnection<T> : IAsyncEnumerable<T>, IAsyncDisposab
59
68
  /// <summary>The transport that last opened; null after a drop, until the next open.</summary>
60
69
  public TransportKind? ProvenTransport => _loop.Proven;
61
70
 
71
+ /// <summary>Each message as it is decoded, before the enumeration yields it; a handler that throws is ignored.</summary>
72
+ public event Action<TIn>? Message;
73
+
74
+ /* the operation declares its messages: a message that is no JSON is no message */
75
+ internal bool Strict { get; init; }
76
+
62
77
  /// <summary>Opens the first adapter in order that opens; the last failure when none does.</summary>
63
78
  public Task ConnectAsync(CancellationToken cancellationToken = default) => _loop.ConnectAsync(cancellationToken);
64
79
 
65
80
  /// <summary>The messages in order; its token, once fired, leaves the connection reconnecting.</summary>
66
- public IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken cancellationToken = default) => MessagesAsync(cancellationToken);
81
+ public IAsyncEnumerator<TIn> GetAsyncEnumerator(CancellationToken cancellationToken = default) => MessagesAsync(cancellationToken);
82
+
83
+ /// <summary>Sends <paramref name="value"/> as its JSON text over the open transport.</summary>
84
+ public Task SendAsync(TOut value, CancellationToken cancellationToken = default) =>
85
+ _loop.SendAsync(JsonSerializer.Serialize(value, _write), cancellationToken);
67
86
 
68
87
  /// <summary>Sends <paramref name="text"/> as it is over the open transport (an SSE or long-poll one POSTs it).</summary>
69
88
  public Task SendAsync(string text, CancellationToken cancellationToken = default) => _loop.SendAsync(text, cancellationToken);
70
89
 
71
- /// <summary>Sends <paramref name="value"/> as its JSON text.</summary>
72
- public Task SendAsync<TValue>(TValue value, JsonTypeInfo<TValue> info, CancellationToken cancellationToken = default) =>
73
- _loop.SendAsync(JsonSerializer.Serialize(value, info), cancellationToken);
74
-
75
90
  /// <summary>Closes the open transport and ends a pending read in any task with no message.</summary>
76
91
  public Task CloseAsync() => _loop.CloseAsync();
77
92
 
78
93
  /// <summary>Closes the connection, as <see cref="CloseAsync"/> does.</summary>
79
94
  public ValueTask DisposeAsync() => new(CloseAsync());
80
95
 
81
- internal ResumableConnection<T> Bound(CancellationToken call)
96
+ internal ResumableConnection<TIn, TOut> Bound(CancellationToken call)
82
97
  {
83
98
  _loop.Bind(call);
84
99
  return this;
85
100
  }
86
101
 
87
- private async IAsyncEnumerator<T> MessagesAsync(CancellationToken token)
102
+ private async IAsyncEnumerator<TIn> MessagesAsync(CancellationToken token)
88
103
  {
89
104
  while (await _loop.NextAsync(token).ConfigureAwait(false) is { } message)
90
105
  {
91
- yield return Deliver(message);
106
+ var value = Deliver(message);
107
+ TypedWebSocket.Fire(Message, value);
108
+ yield return value;
92
109
  }
93
110
  }
94
111
 
95
- /* the message as JSON, else as a JSON string of its text; the cursor advanced before it decodes */
96
- private T Deliver(TransportMessage message)
112
+ /* the message as JSON, else (unless strict) as a JSON string of its text; the cursor advanced before it decodes */
113
+ private TIn Deliver(TransportMessage message)
97
114
  {
98
- JsonElement payload;
115
+ JsonElement payload = default;
116
+ JsonException? malformed = null;
99
117
  try
100
118
  {
101
119
  using var document = JsonDocument.Parse(message.Text);
102
120
  payload = document.RootElement.Clone();
103
121
  }
122
+ catch (JsonException e) when (Strict)
123
+ {
124
+ malformed = e;
125
+ }
104
126
  catch (JsonException)
105
127
  {
106
128
  payload = JsonSerializer.SerializeToElement(message.Text, Arg.StringInfo);
107
129
  }
108
130
  Options.Advance(message.Id, payload);
131
+ if (malformed is not null)
132
+ {
133
+ throw new DecodeException($"realtime message is not valid JSON: {malformed.Message}", malformed);
134
+ }
135
+ var what = Strict ? "realtime message" : "a message";
109
136
  try
110
137
  {
111
- return JsonSerializer.Deserialize(payload, _info) ?? throw new DecodeException("a message does not decode: it is null");
138
+ return JsonSerializer.Deserialize(payload, _read) ?? throw new DecodeException($"{what} does not decode: it is null");
112
139
  }
113
140
  catch (JsonException e)
114
141
  {
115
- throw new DecodeException($"a message does not decode: {e.Message}", e);
142
+ throw new DecodeException($"{what} does not decode: {e.Message}", e);
116
143
  }
117
144
  }
118
145
  }
@@ -10,7 +10,7 @@ using System.Threading.Tasks;
10
10
 
11
11
  namespace Http.Runtime;
12
12
 
13
- /* ResumableConnection<T>'s loop (Python's realtime.py), its behavior documented there */
13
+ /* ResumableConnection<TIn, TOut>'s loop (Python's realtime.py), its behavior documented there */
14
14
  internal sealed class RealtimeLoop(IReadOnlyList<ITransportAdapter> adapters, TransportOptions options, string url)
15
15
  {
16
16
  public static readonly TimeSpan OpenLimit = TimeSpan.FromSeconds(30);
@@ -26,11 +26,11 @@ public sealed class SseAdapter : ITransportAdapter, IDialed
26
26
  var x = _dial.Stream(options);
27
27
  var live = await x.OpenAsync(cancellationToken).ConfigureAwait(false);
28
28
  _dial.Opened(x.Raw!);
29
- return new SseConnection(new EventStream<string>(live, data => data, CancellationToken.None), _dial);
29
+ return new SseConnection(new EventStream<SseEvent<string>>(live, e => e, CancellationToken.None), _dial);
30
30
  }
31
31
  }
32
32
 
33
- internal sealed class SseConnection(EventStream<string> stream, Dial dial) : ITransportConnection
33
+ internal sealed class SseConnection(EventStream<SseEvent<string>> stream, Dial dial) : ITransportConnection
34
34
  {
35
35
  private IAsyncEnumerator<SseEvent<string>>? _events;
36
36
 
@@ -38,7 +38,7 @@ internal sealed class SseConnection(EventStream<string> stream, Dial dial) : ITr
38
38
  public async Task<TransportMessage?> ReceiveAsync(CancellationToken cancellationToken)
39
39
  {
40
40
  _events ??= stream.GetAsyncEnumerator();
41
- using var ended = cancellationToken.Register(static stream => ((EventStream<string>)stream!).DisposeAsync(), stream);
41
+ using var ended = cancellationToken.Register(static stream => ((EventStream<SseEvent<string>>)stream!).DisposeAsync(), stream);
42
42
  if (!await _events.MoveNextAsync().ConfigureAwait(false))
43
43
  {
44
44
  cancellationToken.ThrowIfCancellationRequested();
@@ -283,7 +283,7 @@ public sealed class TypedWebSocket : IAsyncDisposable
283
283
  return reason[..end];
284
284
  }
285
285
 
286
- private static void Fire<T>(Action<T>? handlers, T value)
286
+ internal static void Fire<T>(Action<T>? handlers, T value)
287
287
  {
288
288
  foreach (var handler in handlers?.GetInvocationList() ?? [])
289
289
  {
@@ -2,12 +2,14 @@
2
2
  using System;
3
3
  using System.Collections.Generic;
4
4
  using System.IO;
5
+ using System.IO.Compression;
5
6
  using System.Linq;
6
7
  using System.Net;
7
8
  using System.Net.Http;
8
9
  using System.Net.WebSockets;
9
10
  using System.Security.Cryptography;
10
11
  using System.Text;
12
+ using System.Text.Json.Serialization.Metadata;
11
13
  using System.Threading;
12
14
  using System.Threading.Tasks;
13
15
 
@@ -18,6 +20,10 @@ internal sealed partial class Transport
18
20
  public async Task<TypedWebSocket> SocketAsync(Operation op, Call call, IReadOnlyList<string>? protocols, string? reconnectToken, CancellationToken cancellationToken) =>
19
21
  (await WsDial.DialAsync(this, new Exchange(this, op, call with { Query = [.. call.Query, Arg.Text("reconnect_token", reconnectToken)] }, stream: true), protocols ?? [], cancellationToken).ConfigureAwait(false))
20
22
  .Bound(cancellationToken);
23
+
24
+ /* a socket whose messages are declared: read as TIn, sent as TOut */
25
+ public async Task<TypedWebSocket<TIn, TOut>> TypedSocketAsync<TIn, TOut>(Operation op, Call call, IReadOnlyList<string>? protocols, string? reconnectToken, JsonTypeInfo<TIn> read, JsonTypeInfo<TOut> write, CancellationToken cancellationToken) =>
26
+ new(await SocketAsync(op, call, protocols, reconnectToken, cancellationToken).ConfigureAwait(false), read, write);
21
27
  }
22
28
 
23
29
  internal static class WsDial
@@ -42,7 +48,7 @@ internal static class WsDial
42
48
  throw new ApiConnectionException($"the WebSocket handshake failed: {refusal}");
43
49
  }
44
50
  x.Raw?.Fill(101, headers, [], SocketUrl(url));
45
- var stream = await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false);
51
+ var stream = Connection(await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false));
46
52
  var options = new WebSocketCreationOptions { SubProtocol = chosen, KeepAliveInterval = KeepAlive, KeepAliveTimeout = KeepAlive };
47
53
  return new TypedWebSocket(WebSocket.CreateFromStream(stream, options), chosen, response);
48
54
  }
@@ -53,6 +59,18 @@ internal static class WsDial
53
59
  }
54
60
  }
55
61
 
62
+ /*
63
+ * a 101's content is the connection, no coded body: a handler's decoder over it for a Content-Encoding is
64
+ * read-only, so the dial takes what lies beneath; .NET's deflate decoder exposes nothing beneath it
65
+ */
66
+ private static Stream Connection(Stream stream) => stream switch
67
+ {
68
+ GZipStream gzip => gzip.BaseStream,
69
+ BrotliStream brotli => brotli.BaseStream,
70
+ { CanWrite: false } => throw new ApiConnectionException("the WebSocket handshake failed: the handler decoded the 101's content, so the connection is read-only"),
71
+ _ => stream,
72
+ };
73
+
56
74
  private static Uri SocketUrl(Uri url) => new UriBuilder(url) { Scheme = url.Scheme == Uri.UriSchemeHttps ? "wss" : "ws" }.Uri;
57
75
 
58
76
  private static HttpRequestMessage Request(Uri url, Dictionary<string, string> headers, string key, IReadOnlyList<string> protocols)