sattleme-checkout 1.0.0

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 (46) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +66 -0
  3. data/LICENSE +21 -0
  4. data/README.md +754 -0
  5. data/SECURITY.md +25 -0
  6. data/lib/sattleme/checkout/cancellation.rb +195 -0
  7. data/lib/sattleme/checkout/client.rb +1438 -0
  8. data/lib/sattleme/checkout/errors.rb +165 -0
  9. data/lib/sattleme/checkout/http_client.rb +294 -0
  10. data/lib/sattleme/checkout/internal/bolt11.rb +187 -0
  11. data/lib/sattleme/checkout/internal/channel.rb +147 -0
  12. data/lib/sattleme/checkout/internal/checkout_link.rb +294 -0
  13. data/lib/sattleme/checkout/internal/concurrency.rb +450 -0
  14. data/lib/sattleme/checkout/internal/crypto.rb +63 -0
  15. data/lib/sattleme/checkout/internal/currencies.rb +47 -0
  16. data/lib/sattleme/checkout/internal/declaration.rb +135 -0
  17. data/lib/sattleme/checkout/internal/derive.rb +153 -0
  18. data/lib/sattleme/checkout/internal/event.rb +110 -0
  19. data/lib/sattleme/checkout/internal/http.rb +129 -0
  20. data/lib/sattleme/checkout/internal/json.rb +457 -0
  21. data/lib/sattleme/checkout/internal/key.rb +116 -0
  22. data/lib/sattleme/checkout/internal/lnurl.rb +238 -0
  23. data/lib/sattleme/checkout/internal/nip44.rb +113 -0
  24. data/lib/sattleme/checkout/internal/onchain/address.rb +58 -0
  25. data/lib/sattleme/checkout/internal/onchain/basics.rb +352 -0
  26. data/lib/sattleme/checkout/internal/onchain/lease.rb +326 -0
  27. data/lib/sattleme/checkout/internal/onchain/merchant_acceptance.rb +168 -0
  28. data/lib/sattleme/checkout/internal/onchain/node.rb +285 -0
  29. data/lib/sattleme/checkout/internal/onchain/payment.rb +345 -0
  30. data/lib/sattleme/checkout/internal/onchain/rest.rb +323 -0
  31. data/lib/sattleme/checkout/internal/onchain/watch.rb +119 -0
  32. data/lib/sattleme/checkout/internal/onchain/witness.rb +260 -0
  33. data/lib/sattleme/checkout/internal/order.rb +228 -0
  34. data/lib/sattleme/checkout/internal/protocol.rb +260 -0
  35. data/lib/sattleme/checkout/internal/rates.rb +373 -0
  36. data/lib/sattleme/checkout/internal/record.rb +179 -0
  37. data/lib/sattleme/checkout/internal/relay_pool.rb +823 -0
  38. data/lib/sattleme/checkout/internal/sales.rb +238 -0
  39. data/lib/sattleme/checkout/internal/secp256k1.rb +234 -0
  40. data/lib/sattleme/checkout/internal/text.rb +144 -0
  41. data/lib/sattleme/checkout/internal/urls.rb +172 -0
  42. data/lib/sattleme/checkout/models.rb +247 -0
  43. data/lib/sattleme/checkout/version.rb +9 -0
  44. data/lib/sattleme/checkout/websocket_client.rb +487 -0
  45. data/lib/sattleme/checkout.rb +72 -0
  46. metadata +112 -0
@@ -0,0 +1,823 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sattleme
4
+ module Checkout
5
+ module Internal
6
+ # Nostr relays (NIP-01, NIP-42; SPEC.md §13), ported from the merchant's app. A call opens one
7
+ # connection per relay, every read and write of the call goes over it, and it is closed once
8
+ # the call is done. Every relay of a list at once, each in a thread of its own; a call goes on
9
+ # as soon as a majority of them answered (any two majorities of one list share a relay).
10
+ # Subscription ids are random: what a relay receives names nothing of the integration.
11
+ module Relay
12
+ # NIP-42 prefix of a refusal that authentication may lift.
13
+ AUTH_REQUIRED = "auth-required:"
14
+
15
+ # A request to a relay failed: no answer in time, a connection that failed or closed, a
16
+ # query CLOSED, an event refused.
17
+ class Failure < StandardError; end
18
+
19
+ # A relay's refusal of an event (NIP-01 `OK` false), with its reason.
20
+ class Refusal < Failure
21
+ attr_reader :reason
22
+
23
+ def initialize(url, reason)
24
+ @reason = reason
25
+ super("#{url} refused the event: #{reason}")
26
+ end
27
+ end
28
+
29
+ # What a read keeps of an event a relay sent (SPEC.md §13), as it comes: its `id` (one
30
+ # longer than 64 bytes by its SHA-256), its `created_at` when it is a safe integer, and
31
+ # what the read's `keep` kept of it (`kept` false: nothing, the event dropped there).
32
+ Entry = Data.define(:id, :created_at, :value, :kept)
33
+
34
+ # What a read of a list gives: the events of each relay that answered (its read ended), and
35
+ # whether a majority of the list answered (Relay.outcome): else the read is no answer
36
+ # (network), never an absence. On every relay (SPEC.md §13), the pages that a relay still
37
+ # reading had sent are among the events too, and that is all: such a relay has not answered.
38
+ Answers = Data.define(:answers, :answered)
39
+
40
+ # What a complete read of a list gives: as Answers, and whether it is complete: a majority
41
+ # of the list read completely (Relay.outcome).
42
+ CompleteAnswers = Data.define(:answers, :answered, :complete)
43
+
44
+ # What a read of a list gives once it goes on (Relay.outcome): whether a majority of the
45
+ # list answered, and whether a majority read completely.
46
+ Outcome = Data.define(:answered, :complete)
47
+
48
+ # How a read of a list stands (SPEC.md §13): how many relays answered, how many read
49
+ # completely, how many are still reading.
50
+ Tally = Data.define(:answered, :complete, :reading)
51
+
52
+ module_function
53
+
54
+ # More than half of `count` relays: any two majorities of one list share a relay.
55
+ def majority(count)
56
+ (count / 2) + 1
57
+ end
58
+
59
+ # The Tally of a read from the read of each relay: :complete or :incomplete once it ended
60
+ # (of a read that is not a complete read, any read that ended is :incomplete), :failed, or
61
+ # :reading while it goes on. Only a relay whose read ended answered: one still reading has
62
+ # not, whatever pages it sent (SPEC.md §13, "Reads on every relay").
63
+ def tally(states)
64
+ Tally.new(answered: states.count { |state| %i[complete incomplete].include?(state) },
65
+ complete: states.count(:complete), reading: states.count(:reading))
66
+ end
67
+
68
+ # What a read of a list gives once it goes on (SPEC.md §13), from what the read of each relay
69
+ # of the list is then (`states`, as #tally reads them): whether a majority of the list
70
+ # answered (their reads ended, complete or not: a relay still reading never did, whatever
71
+ # pages it sent), else the read is no answer (network); and whether a majority read
72
+ # completely, which makes a complete read complete. The pool's reads give it, and only it.
73
+ def outcome(states)
74
+ needed = majority(states.size)
75
+ counted = tally(states)
76
+ Outcome.new(answered: counted.answered >= needed, complete: counted.complete >= needed)
77
+ end
78
+
79
+ # The entry of `value`, a relay's event: its id when it is a string, its date when it is a
80
+ # safe integer, and what `keep` gives of it (nil: nothing kept). `read` holds the ids of the
81
+ # query so far: an event of one of them again (a copy, or a forgery: an id is its event's
82
+ # hash) is counted, never kept nor checked again (SPEC.md §13, Limits).
83
+ def entry_of(value, keep, read = nil)
84
+ fields = value.is_a?(Hash) ? value : {}
85
+ id = fields["id"]
86
+ id = nil unless id.is_a?(String)
87
+ id = "##{Text.hex(Crypto.sha256(id.b))}" if id && id.bytesize > 64
88
+ created_at = Json.safe_integer?(fields["created_at"]) ? fields["created_at"].to_i : nil
89
+ if id && read
90
+ return Entry.new(id: id, created_at: created_at, value: nil, kept: false) if read.key?(id)
91
+
92
+ read[id] = true
93
+ end
94
+ kept = keep.call(value)
95
+ Entry.new(id: id, created_at: created_at, value: kept, kept: !kept.nil?)
96
+ end
97
+
98
+ # One page of a paged read (SPEC.md §13, "Paged reads"), read: the next page's `until`, or nil
99
+ # when the read ends there. Its events with a string `id` and a safe integer `created_at`
100
+ # page the read, whatever else they hold (one that does not check out pages it all the
101
+ # same): `until` is the oldest such `created_at`, minus 1 when none of them was new to the
102
+ # read. `seen` holds the ids of the read so far; the page's new ones are added to it, and
103
+ # what the read keeps of them to `kept`. An event without these two members is not kept.
104
+ def after_paged_page(answer, seen, kept)
105
+ oldest = nil
106
+ fresh = false
107
+ answer.each do |entry|
108
+ next if entry.id.nil? || entry.created_at.nil?
109
+
110
+ oldest = oldest.nil? ? entry.created_at : [oldest, entry.created_at].min
111
+ next if seen.key?(entry.id)
112
+
113
+ seen[entry.id] = true
114
+ kept << entry.value if entry.kept
115
+ fresh = true
116
+ end
117
+ return nil if oldest.nil?
118
+
119
+ fresh ? oldest : oldest - 1
120
+ end
121
+
122
+ # One page of a complete read (SPEC.md §13, "Complete reads"), read: [:until, t], the next
123
+ # page's `until`, or [:complete, whether it is]. `seen` holds the ids of the read so far;
124
+ # the page's new ones are added to it, and the events kept of them to `kept`.
125
+ def after_complete_page(answer, seen, kept, pages_read)
126
+ oldest = nil
127
+ fresh = false
128
+ answer.each do |entry|
129
+ next if entry.id.nil?
130
+
131
+ oldest = oldest.nil? ? entry.created_at : [oldest, entry.created_at].min unless entry.created_at.nil?
132
+ next if seen.key?(entry.id)
133
+
134
+ seen[entry.id] = true
135
+ kept << entry.value if entry.kept
136
+ # New, dated or not ("no event not seen before"): the next page may hold more.
137
+ fresh = true
138
+ end
139
+ # More than asked: the relay ignored the limit, and what it left out cannot be told.
140
+ return [:complete, false] if answer.size > Protocol::COMPLETE_READ_LIMIT
141
+ return [:complete, true] if answer.size < Protocol::COMPLETE_READ_LIMIT
142
+ # Full: the next page from its oldest second, unless it cannot move on.
143
+ return [:complete, false] if oldest.nil? || !fresh || pages_read >= Protocol::MAX_PAGES
144
+
145
+ [:until, oldest]
146
+ end
147
+
148
+ # What each relay of a read sent so far, page after page: a read on every relay cut short
149
+ # keeps the pages of the relays still reading. Thread-safe.
150
+ class Sent
151
+ def initialize
152
+ @mutex = Mutex.new
153
+ @values = []
154
+ end
155
+
156
+ def <<(value)
157
+ @mutex.synchronize { @values << value }
158
+ self
159
+ end
160
+
161
+ def to_a
162
+ @mutex.synchronize { @values.dup }
163
+ end
164
+
165
+ def empty?
166
+ @mutex.synchronize { @values.empty? }
167
+ end
168
+ end
169
+
170
+ # One connection to one relay, shared by every request of a pool: opened in a thread of its
171
+ # own, which then reads its messages and hands each to the requests listening.
172
+ class Connection
173
+ attr_reader :url
174
+
175
+ def initialize(url, websocket, timeout)
176
+ @url = url
177
+ @mutex = Mutex.new
178
+ @changed = ConditionVariable.new
179
+ @state = :connecting
180
+ @socket = nil
181
+ @send_mutex = Mutex.new
182
+ @listeners = {}
183
+ @deaths = {}
184
+ @next = 0
185
+ # NIP-42 answers, by public key and challenge: one AUTH per key per challenge.
186
+ @auths = {}
187
+ @challenge = nil
188
+ @handshake = Cancellation.new
189
+ @thread = Thread.new { run(websocket, timeout) }
190
+ @thread.name = "sattleme-checkout relay"
191
+ @thread.report_on_exception = false
192
+ end
193
+
194
+ # Waits until the connection is open: :open, :timeout once `deadline` passed; raises
195
+ # Failure when it failed, as Stop#raise! does once `stop` stopped.
196
+ def wait_open(stop, deadline)
197
+ handle = stop.on_stop { @mutex.synchronize { @changed.broadcast } }
198
+ @mutex.synchronize do
199
+ loop do
200
+ return :open if @state == :open
201
+ raise Failure, "#{@url}: connection failed" if @state == :dead
202
+
203
+ stop.raise! if stop.stopped?
204
+ left = Clock.left(deadline)
205
+ return :timeout if left.zero?
206
+
207
+ @changed.wait(@mutex, left)
208
+ end
209
+ end
210
+ ensure
211
+ stop.remove(handle)
212
+ end
213
+
214
+ # Hears every message of the relay (in the connection's thread: quick) until #unlisten.
215
+ def listen(&listener)
216
+ @mutex.synchronize do
217
+ next nil if @state == :dead
218
+
219
+ @next += 1
220
+ @listeners[@next] = listener
221
+ @next
222
+ end
223
+ end
224
+
225
+ def unlisten(handle)
226
+ @mutex.synchronize { @listeners.delete(handle) } if handle
227
+ end
228
+
229
+ # Hears the end of the connection (at once when it is over already).
230
+ def on_death(&listener)
231
+ handle = @mutex.synchronize do
232
+ next nil if @state == :dead
233
+
234
+ @next += 1
235
+ @deaths[@next] = listener
236
+ @next
237
+ end
238
+ listener.call if handle.nil?
239
+ handle
240
+ end
241
+
242
+ def remove_death(handle)
243
+ @mutex.synchronize { @deaths.delete(handle) } if handle
244
+ end
245
+
246
+ # Sends a message (JSON); a failure to send ends the connection.
247
+ def transmit(message)
248
+ socket = @mutex.synchronize { @state == :open ? @socket : nil }
249
+ return if socket.nil?
250
+
251
+ @send_mutex.synchronize { socket.send_text(Json.generate(message)) }
252
+ rescue StandardError
253
+ die
254
+ end
255
+
256
+ # Answers the relay's NIP-42 challenge with `auth_key`: whether the relay took it, before
257
+ # `deadline` (:timeout after). One AUTH per key and challenge, shared by the requests that
258
+ # ask for it.
259
+ def authenticate(auth_key, created_at, random, stop, deadline)
260
+ public_key = Events.public_key(auth_key)
261
+ challenge = nil
262
+ created = false
263
+ future = @mutex.synchronize do
264
+ next nil if @state != :open || @challenge.nil?
265
+
266
+ challenge = @challenge
267
+ @auths["#{public_key}:#{challenge}"] ||= begin
268
+ created = true
269
+ Future.new
270
+ end
271
+ end
272
+ return false if future.nil?
273
+
274
+ send_auth(future, auth_key, challenge, created_at, random) if created
275
+ return :timeout unless future.wait(stop, deadline)
276
+
277
+ future.outcome[1] == true
278
+ end
279
+
280
+ # Waits until the connection's thread ended, `seconds` at most.
281
+ def join(seconds)
282
+ Internal.join(@thread, seconds)
283
+ end
284
+
285
+ # Closes the connection; every request still on it fails.
286
+ def close
287
+ @handshake.cancel
288
+ socket = @mutex.synchronize { @socket }
289
+ die
290
+ begin
291
+ socket&.close
292
+ rescue StandardError
293
+ nil
294
+ end
295
+ end
296
+
297
+ private
298
+
299
+ def send_auth(future, auth_key, challenge, created_at, random)
300
+ auth = Events.sign(auth_key, random, created_at: created_at, kind: Protocol::AUTH_KIND,
301
+ tags: [["relay", @url], ["challenge", challenge]], content: "")
302
+ listener = listen do |message|
303
+ future.fulfill(message[2] == true) if message[0] == "OK" && message[1] == auth.id
304
+ end
305
+ death = on_death { future.fulfill(false) }
306
+ future.on_settle do
307
+ unlisten(listener)
308
+ remove_death(death)
309
+ end
310
+ transmit(["AUTH", auth.to_h])
311
+ end
312
+
313
+ def run(websocket, timeout)
314
+ socket = websocket.connect(@url, timeout: timeout, headers: { "User-Agent" => Protocol::USER_AGENT },
315
+ cancellation: @handshake)
316
+ opened = @mutex.synchronize do
317
+ next false if @state == :dead
318
+
319
+ @socket = socket
320
+ @state = :open
321
+ @changed.broadcast
322
+ true
323
+ end
324
+ return socket.close unless opened
325
+
326
+ while (text = socket.receive)
327
+ dispatch(text)
328
+ end
329
+ die
330
+ rescue StandardError
331
+ die
332
+ end
333
+
334
+ def dispatch(text)
335
+ text = Text.decode_utf8(text) unless Text.well_formed?(text)
336
+ message = text && Json.parse_or(text)
337
+ return unless message.is_a?(Array)
338
+
339
+ listeners = @mutex.synchronize do
340
+ # The last challenge counts.
341
+ @challenge = message[1] if message[0] == "AUTH" && Text.well_formed?(message[1])
342
+ @listeners.values
343
+ end
344
+ listeners.each { |listener| listener.call(message) }
345
+ end
346
+
347
+ def die
348
+ deaths = @mutex.synchronize do
349
+ next [] if @state == :dead
350
+
351
+ @state = :dead
352
+ @changed.broadcast
353
+ @listeners.clear
354
+ @deaths.values.tap { @deaths.clear }
355
+ end
356
+ deaths.each(&:call)
357
+ end
358
+ end
359
+
360
+ # The relays of one call: one connection per relay, opened at its first request, kept for
361
+ # the call's next requests, closed by #close or #release. Each request (a page of a read, a
362
+ # publication) is bounded by `timeout_ms`, the wait for the connection included.
363
+ class Pool
364
+ def initialize(websocket:, timeout_ms:, stop:, random:, now:)
365
+ @websocket = websocket
366
+ @timeout = timeout_ms / 1000.0
367
+ @stop = stop
368
+ # What a publication's writes wait with: stopped by the call's cancellation alone, not by
369
+ # its end, so that a publication's relays past its majority finish their own request
370
+ # once the call returned (SPEC.md §13), each within its timeout.
371
+ @tail = Stop.new(stop.cancellation)
372
+ @random = random
373
+ @now = now
374
+ @mutex = Mutex.new
375
+ @idle = ConditionVariable.new
376
+ @connections = {}
377
+ # Relays a request to which ran out of time or lost its connection in this call: a read
378
+ # on every relay counts them as failed at once (SPEC.md §13).
379
+ @failed = {}
380
+ # The writes of publications not ended yet, by relay.
381
+ @writes = Hash.new(0)
382
+ @released = false
383
+ @closed = false
384
+ end
385
+
386
+ # What every relay of `relays` holds that matches `filter`, at once, page after page when
387
+ # `paged`. Returns as soon as a majority of them answered (the others' reads are dropped),
388
+ # or once every relay answered or failed: Answers, the events kept of each relay that
389
+ # answered, and whether a majority did (Relay.outcome). On every relay (`every_relay`), the
390
+ # others are waited for one timeout more at most, the relays that failed earlier in the
391
+ # call count as failed at once, and the pages of a relay still reading are kept, as events
392
+ # only: it has not answered. Raises only Cancelled.
393
+ def query_relays(relays, filter, auth_key, paged:, keep:, every_relay: false, stop: @stop)
394
+ needed = Relay.majority(relays.size)
395
+ asked = every_relay ? relays.reject { |relay| failed?(relay) } : relays
396
+ states = initial_states(relays, asked)
397
+ sent = asked.to_h { |relay| [relay, Sent.new] }
398
+ answers = {}
399
+ gather(asked, stop) do |inbox, read|
400
+ read.call do |relay, read_stop|
401
+ if paged
402
+ pages(relay, filter, auth_key, keep, read_stop, sent[relay])
403
+ else
404
+ query(relay, filter, auth_key, keep, read_stop).filter_map { |entry| entry.value if entry.kept }
405
+ end
406
+ end
407
+ grace = nil
408
+ loop do
409
+ tally = Relay.tally(states.values)
410
+ break if tally.reading.zero?
411
+
412
+ if tally.answered >= needed
413
+ break unless every_relay
414
+
415
+ grace ||= Clock.now + @timeout
416
+ end
417
+ message = inbox.pop(stop, grace)
418
+ break if message.equal?(Inbox::TIMEOUT)
419
+
420
+ relay, state, events = message
421
+ answers[relay] = events if state == :ok
422
+ states[relay] = state == :ok ? :incomplete : :failed
423
+ end
424
+ end
425
+ keep_still_reading(answers, sent, states) if every_relay
426
+ Answers.new(answers: answers, answered: Relay.outcome(states.values).answered)
427
+ end
428
+
429
+ # A complete read of `filter` on every relay of `relays` at once (SPEC.md §13, "Complete
430
+ # reads"): pages of COMPLETE_READ_LIMIT events, the next one from the oldest second of the
431
+ # last, until a page is not full. Returns as soon as a majority of them read completely
432
+ # (the others' reads are dropped), or once every relay answered, stopped incomplete or
433
+ # failed: CompleteAnswers (Relay.outcome), a relay whose read ended (complete or not)
434
+ # having answered. On every relay, as #query_relays, and no wait once a majority can no
435
+ # longer read completely: a relay still reading then has not answered either, its pages
436
+ # kept as events only. Raises only Cancelled.
437
+ def query_complete(relays, filter, auth_key, keep:, every_relay: false, stop: @stop)
438
+ needed = Relay.majority(relays.size)
439
+ asked = every_relay ? relays.reject { |relay| failed?(relay) } : relays
440
+ states = initial_states(relays, asked)
441
+ sent = asked.to_h { |relay| [relay, Sent.new] }
442
+ answers = {}
443
+ gather(asked, stop) do |inbox, read|
444
+ read.call { |relay, read_stop| complete_pages(relay, filter, auth_key, keep, read_stop, sent[relay]) }
445
+ grace = nil
446
+ loop do
447
+ tally = Relay.tally(states.values)
448
+ break if tally.reading.zero?
449
+ # On every relay, no wait once a majority can no longer read completely.
450
+ break if every_relay && tally.complete + tally.reading < needed
451
+
452
+ if tally.complete >= needed
453
+ break unless every_relay
454
+
455
+ grace ||= Clock.now + @timeout
456
+ end
457
+ message = inbox.pop(stop, grace)
458
+ break if message.equal?(Inbox::TIMEOUT)
459
+
460
+ relay, state, read_result = message
461
+ if state == :ok
462
+ events, whole = read_result
463
+ answers[relay] = events
464
+ states[relay] = whole ? :complete : :incomplete
465
+ else
466
+ states[relay] = :failed
467
+ end
468
+ end
469
+ end
470
+ keep_still_reading(answers, sent, states) if every_relay
471
+ outcome = Relay.outcome(states.values)
472
+ CompleteAnswers.new(answers: answers, answered: outcome.answered, complete: outcome.complete)
473
+ end
474
+
475
+ # Publishes `event` to every relay of `relays` at once. Returns once `quorum` relays took
476
+ # it: the others, its tail, go on, each until its own request ends (NIP-42's one
477
+ # authentication and the one write again included), within its timeout, the call returned
478
+ # or not (SPEC.md §13). Raises Failure as soon as they no longer can, as Stop#raise! does
479
+ # once `stop` stops: its writes are then stopped, and over, first.
480
+ def publish_to_quorum(relays, event, auth_key, quorum, stop: @stop)
481
+ publication = @tail.child
482
+ inbox = Inbox.new
483
+ writers = relays.map do |relay|
484
+ # Counted at once: #release keeps the connection of a write, started or not.
485
+ @mutex.synchronize { @writes[relay] += 1 }
486
+ Internal.thread("sattleme-checkout relay write", call: false) do
487
+ publish(relay, event, auth_key, publication)
488
+ inbox << :taken
489
+ rescue Stopped, Cancelled
490
+ inbox << :stopped
491
+ rescue StandardError
492
+ inbox << :failed
493
+ ensure
494
+ written(relay)
495
+ end
496
+ end
497
+ taken = 0
498
+ failures = 0
499
+ loop do
500
+ if taken >= quorum
501
+ writers = nil
502
+ return true
503
+ end
504
+ raise Failure, "Fewer than #{quorum} relays took the event" if relays.size - failures < quorum
505
+
506
+ message = inbox.pop(stop)
507
+ message == :taken ? taken += 1 : failures += 1
508
+ end
509
+ ensure
510
+ # It failed, or its call stopped or was cancelled: none of its writes is a tail.
511
+ if writers
512
+ publication.stop
513
+ writers.each { |writer| Internal.join(writer) }
514
+ end
515
+ end
516
+
517
+ # Whether a request to `relay` ran out of time or lost its connection in this call.
518
+ def failed?(relay)
519
+ @mutex.synchronize { @failed.key?(relay) }
520
+ end
521
+
522
+ # Closes every connection now (their requests fail), and waits until each one's thread
523
+ # ended.
524
+ def close
525
+ connections = @mutex.synchronize do
526
+ @closed = true
527
+ @connections.values.tap { @connections.clear }
528
+ end
529
+ close_all(connections)
530
+ @tail.release
531
+ end
532
+
533
+ # The call is done (SPEC.md §13): closes now each connection that no publication's write
534
+ # still uses (the requests still on it fail), the others once those writes are over (the
535
+ # tails of publications, each within its timeout), in a thread of their own: the call
536
+ # returns at once. Nothing new may be asked of the pool but those writes.
537
+ def release
538
+ idle = @mutex.synchronize do
539
+ @released = true
540
+ @connections.select { |url, _| @writes[url].zero? }.each_key { |url| @connections.delete(url) }
541
+ end
542
+ close_all(idle.values)
543
+ return close unless @mutex.synchronize { @writes.values.any?(&:positive?) }
544
+
545
+ Internal.thread("sattleme-checkout relay release", call: false) do
546
+ @mutex.synchronize { @idle.wait(@mutex) while @writes.values.any?(&:positive?) }
547
+ close
548
+ end
549
+ nil
550
+ end
551
+
552
+ private
553
+
554
+ def spawn(name, &)
555
+ Internal.thread(name, call: false, &)
556
+ end
557
+
558
+ # Closes `connections`, then waits until each one's thread ended (STOP_GRACE_SECONDS at
559
+ # most: a WebSocket client of the integrator's may not stop when it is told).
560
+ def close_all(connections)
561
+ connections.each(&:close)
562
+ deadline = Clock.now + STOP_GRACE_SECONDS
563
+ connections.each { |connection| connection.join(Clock.left(deadline)) }
564
+ end
565
+
566
+ # A write of a publication to `relay` ended.
567
+ def written(relay)
568
+ @mutex.synchronize do
569
+ @writes[relay] -= 1
570
+ @idle.broadcast
571
+ end
572
+ end
573
+
574
+ # The read of each relay of `relays` as a read starts (Relay.tally): reading, but those left
575
+ # out of `asked`, which failed earlier in the call.
576
+ def initial_states(relays, asked)
577
+ relays.to_h { |relay| [relay, asked.include?(relay) ? :reading : :failed] }
578
+ end
579
+
580
+ # Of a read on every relay, the pages that each relay still reading had sent: kept as
581
+ # events, though it has not answered.
582
+ def keep_still_reading(answers, sent, states)
583
+ sent.each do |relay, events|
584
+ answers[relay] = events.to_a if states[relay] == :reading && !events.empty?
585
+ end
586
+ end
587
+
588
+ # Runs the reads of `asked` (each relay in its thread, with a stop of the read) and the
589
+ # block that waits for them; once it returns, every read still running is stopped, and
590
+ # waited for until it ended: when the read goes on, the relays it dropped ask nothing more
591
+ # (no page, no authentication) and draw no random bytes for it (SPEC.md §13).
592
+ def gather(asked, parent)
593
+ stop = parent.child
594
+ inbox = Inbox.new
595
+ readers = []
596
+ read = lambda do |&run|
597
+ asked.each do |relay|
598
+ readers << spawn("sattleme-checkout relay read") do
599
+ inbox << [relay, :ok, run.call(relay, stop)]
600
+ rescue Stopped, Cancelled
601
+ nil
602
+ rescue StandardError => e
603
+ inbox << [relay, :failed, e]
604
+ end
605
+ end
606
+ end
607
+ yield inbox, read
608
+ ensure
609
+ stop.stop
610
+ readers.each(&:join)
611
+ end
612
+
613
+ # The stored events of `url` that match `filter`, page after page, as the merchant's app
614
+ # reads them (SPEC.md §13, "Paged reads"); a failure after the first page keeps what was
615
+ # read.
616
+ def pages(url, filter, auth_key, keep, stop, events)
617
+ seen = {}
618
+ until_time = filter["until"]
619
+ Protocol::MAX_PAGES.times do |page|
620
+ begin
621
+ answer = query(url, until_time.nil? ? filter : filter.merge("until" => until_time), auth_key, keep,
622
+ stop)
623
+ rescue Failure
624
+ raise if page.zero?
625
+
626
+ break
627
+ end
628
+ until_time = Relay.after_paged_page(answer, seen, events)
629
+ break if until_time.nil?
630
+ end
631
+ events.to_a
632
+ end
633
+
634
+ # The events of `url` that match `filter`, read completely if it can be: [events, whether
635
+ # it was]. Raises when its first page fails (the relay failed); a later failure ends the
636
+ # read incomplete.
637
+ def complete_pages(url, filter, auth_key, keep, stop, events)
638
+ seen = {}
639
+ kept = []
640
+ until_time = filter["until"]
641
+ page = 1
642
+ loop do
643
+ page_filter = filter.merge("limit" => Protocol::COMPLETE_READ_LIMIT)
644
+ page_filter["until"] = until_time unless until_time.nil?
645
+ begin
646
+ answer = query(url, page_filter, auth_key, keep, stop)
647
+ rescue Failure
648
+ raise if page == 1
649
+
650
+ return [events.to_a, false]
651
+ end
652
+ before = kept.size
653
+ step, value = Relay.after_complete_page(answer, seen, kept, page)
654
+ kept[before..].each { |event| events << event }
655
+ return [events.to_a, value] if step == :complete
656
+
657
+ until_time = value
658
+ page += 1
659
+ end
660
+ end
661
+
662
+ # The stored events of `url` that match `filter`, as it sent them: their entries (the
663
+ # event itself only when `keep` takes it), unchecked. At most MAX_EVENTS_PER_QUERY.
664
+ # Authenticates when the relay asks (NIP-42).
665
+ def query(url, filter, auth_key, keep, stop)
666
+ request(url, stop) do |connection, deadline|
667
+ closed, entries = ask(url, connection, filter, keep, stop, deadline)
668
+ if closed&.start_with?(AUTH_REQUIRED) && authenticated?(url, connection, auth_key, stop, deadline)
669
+ closed, entries = ask(url, connection, filter, keep, stop, deadline)
670
+ end
671
+ raise Failure, "#{url} closed the query: #{closed}" unless closed.nil?
672
+
673
+ entries
674
+ end
675
+ end
676
+
677
+ # One REQ: [nil, entries] once the relay sent EOSE or MAX_EVENTS_PER_QUERY events (then
678
+ # CLOSE), or [reason, entries] when it CLOSED the query.
679
+ def ask(url, connection, filter, keep, stop, deadline)
680
+ # Nothing more once the read went on: not even the random bytes of a subscription id, nor
681
+ # its REQ when it went on while they were drawn.
682
+ stop.check!
683
+ subscription = Text.hex(@random.call(8))
684
+ stop.check!
685
+ inbox = Inbox.new
686
+ entries = []
687
+ # The ids of this query's events so far: the first event of each is the one read.
688
+ read = {}
689
+ ending = nil
690
+ mutex = Mutex.new
691
+ listener = connection.listen do |message|
692
+ next unless message[1] == subscription
693
+
694
+ case message[0]
695
+ when "EVENT"
696
+ next if mutex.synchronize { ending }
697
+
698
+ # What is kept of the event, as it comes (SPEC.md §13, Limits).
699
+ entry = Relay.entry_of(message[2], keep, read)
700
+ mutex.synchronize do
701
+ next if ending
702
+
703
+ entries << entry
704
+ if entries.size >= Protocol::MAX_EVENTS_PER_QUERY
705
+ ending = [:full]
706
+ inbox << :end
707
+ end
708
+ end
709
+ when "EOSE", "CLOSED"
710
+ mutex.synchronize do
711
+ next if ending
712
+
713
+ ending = if message[0] == "EOSE"
714
+ [:eose]
715
+ else
716
+ [:closed, message[2].is_a?(String) ? message[2] : ""]
717
+ end
718
+ inbox << :end
719
+ end
720
+ end
721
+ end
722
+ death = connection.on_death { inbox << :dead }
723
+ connection.transmit(["REQ", subscription, filter])
724
+ outcome = inbox.pop(stop, deadline)
725
+ fail!(url, "#{url}: no answer in time") if outcome.equal?(Inbox::TIMEOUT)
726
+ fail!(url, "#{url}: connection failed") if outcome == :dead
727
+
728
+ kind, reason = mutex.synchronize { ending }
729
+ [kind == :closed ? reason : nil, mutex.synchronize { entries.dup }]
730
+ ensure
731
+ # Asked (none when the read went on before):
732
+ if mutex
733
+ connection.unlisten(listener)
734
+ connection.remove_death(death)
735
+ # Over this connection, which stays open for the call's next requests.
736
+ connection.transmit(["CLOSE", subscription]) unless mutex.synchronize { ending }&.first == :closed
737
+ end
738
+ end
739
+
740
+ # Publishes `event` to one relay, authenticating when it asks (NIP-42). Raises unless taken.
741
+ def publish(url, event, auth_key, stop)
742
+ request(url, stop) do |connection, deadline|
743
+ accepted, reason = write(url, connection, event, stop, deadline)
744
+ auth = !accepted && reason.start_with?(AUTH_REQUIRED)
745
+ if auth && authenticated?(url, connection, auth_key, stop, deadline)
746
+ accepted, reason = write(url, connection, event, stop, deadline)
747
+ end
748
+ raise Refusal.new(url, reason) unless accepted
749
+ end
750
+ end
751
+
752
+ def write(url, connection, event, stop, deadline)
753
+ stop.check!
754
+ inbox = Inbox.new
755
+ listener = connection.listen do |message|
756
+ if message[0] == "OK" && message[1] == event.id
757
+ inbox << [message[2] == true, Text.well_formed?(message[3]) ? message[3] : ""]
758
+ end
759
+ end
760
+ death = connection.on_death { inbox << :dead }
761
+ connection.transmit(["EVENT", event.to_h])
762
+ answer = inbox.pop(stop, deadline)
763
+ fail!(url, "#{url}: no answer in time") if answer.equal?(Inbox::TIMEOUT)
764
+ fail!(url, "#{url}: connection failed") if answer == :dead
765
+
766
+ answer
767
+ ensure
768
+ connection.unlisten(listener)
769
+ connection.remove_death(death)
770
+ end
771
+
772
+ def authenticated?(url, connection, auth_key, stop, deadline)
773
+ # No authentication once the read went on: neither the clock nor random bytes for it, nor
774
+ # its AUTH when it went on while the clock was read.
775
+ stop.check!
776
+ created_at = @now.call
777
+ stop.check!
778
+ taken = connection.authenticate(auth_key, created_at, @random, stop, deadline)
779
+ fail!(url, "#{url}: no answer in time") if taken == :timeout
780
+ taken
781
+ end
782
+
783
+ # Runs the block over the connection to `url` once it is open, within the timeout: what it
784
+ # gives. Raises Failure when the connection fails or the time runs out (the relay then
785
+ # counts as failed in this call), as Stop#raise! does when `stop` stops.
786
+ def request(url, stop)
787
+ deadline = Clock.now + @timeout
788
+ # No request once its read went on, nor once its call was cancelled.
789
+ stop.check!
790
+ connection = connection_for(url)
791
+ begin
792
+ state = connection.wait_open(stop, deadline)
793
+ rescue Failure
794
+ fail!(url, "#{url}: connection failed")
795
+ end
796
+ fail!(url, "#{url}: no answer in time") if state == :timeout
797
+ yield connection, deadline
798
+ end
799
+
800
+ # Marks `url` failed in this call, and raises Failure with `message`.
801
+ def fail!(url, message)
802
+ @mutex.synchronize { @failed[url] = true }
803
+ raise Failure, message
804
+ end
805
+
806
+ # The pool's connection to `url`, opened at its first request.
807
+ def connection_for(url)
808
+ @mutex.synchronize do
809
+ # Released: only a publication's write still asks (its relay past its majority).
810
+ raise Failure, "#{url}: the pool is closed" if @closed || (@released && @writes[url].zero?)
811
+
812
+ @connections[url] ||= Connection.new(url, @websocket, @timeout)
813
+ end
814
+ rescue Failure
815
+ raise
816
+ rescue StandardError
817
+ fail!(url, "#{url}: connection failed")
818
+ end
819
+ end
820
+ end
821
+ end
822
+ end
823
+ end