samagotchi 0.111.1 → 0.113.0

data/lib/samagotchi/web/push/attention.rb

@@ -4,12 +4,12 @@ module Samagotchi
   module Web
     module Push
       # When a session needs the user, decided from two of the hub's session
-      # summaries (SessionSummary.build: symbol keys): the server's port of
-      # the page's rules (web/public/notify.js attentionFor, closedKeys,
-      # attentionText), so a push and the tab's notification ring for the
-      # same thing under the same key. P1 pushes approvals and questions
-      # only (the plan's D1): a step-limit question, a card, a failed or
-      # done turn come later. See docs/internals/web-push.md.
+      # summaries (SessionSummary.build: symbol keys, but +last_turn+'s are
+      # strings): the server's port of the page's rules (web/public/notify.js
+      # attentionFor, closedKeys, attentionText), so a push and the tab's
+      # notification ring for the same thing under the same key.
+      # spec/fixtures/attention_cases.json holds the cases both sides answer.
+      # See docs/internals/web-push.md.
       module Attention
         module_function
 
@@ -23,11 +23,20 @@ module Samagotchi
         # (or hook question) waits, as its parent may relay it.
         RELAY_HOLD = 3.5
         RELAYED_KINDS = %w[approval hook].freeze
-        # The reasons P1 pushes.
-        PUSHED = %w[approval question].freeze
+        # The reasons that wait on the user: open until answered, counted in
+        # the badge, cleaned up once answered. A failed or done turn is
+        # neither (nothing to answer).
+        WAITING = %w[approval question continue card].freeze
+        # notify.js DONE_MIN_SECONDS, UNWATCHED_ORIGINS: a finished turn
+        # shorter than this was watched (no "done"), unless nobody started
+        # it (a delegate child's report, a context change, a finished task).
+        DONE_MIN_SECONDS = 10
+        UNWATCHED_ORIGINS = %w[delegate_report context task].freeze
         TITLE_MAX = 61
         BODIES = { "question" => "needs an answer", "approval" => "needs approval", "continue" => "hit its step limit",
-                   "card" => "needs you" }.freeze
+                   "card" => "needs you", "failed" => "turn failed" }.freeze
+
+        def waiting?(reason) = WAITING.include?(reason)
 
         # notify.js questionReason: a hook's question is a question.
         def reason_of(question)
@@ -39,52 +48,81 @@ module Samagotchi
         end
 
         # What +nxt+ newly needs the user for, compared with +prev+ (nil for
-        # a session not seen yet).
+        # a session not seen yet): a new question first, then a new card,
+        # then a finished turn (notify.js attentionFor's order).
         # @return [Event, nil]
         def for(prev, nxt)
           return nil unless nxt && nxt[:id]
 
           question = nxt[:pending_question]
-          return nil unless question && question[:id] && question[:id] != prev&.dig(:pending_question, :id)
-          # Relayed to the parent already: the parent's notifies.
-          return nil if question[:relayed_to]
+          if question.is_a?(Hash) && question[:id] && question[:id] != prev&.dig(:pending_question, :id)
+            # Relayed to the parent already: the parent's notifies.
+            return nil if question[:relayed_to]
 
-          reason = reason_of(question)
-          return nil unless PUSHED.include?(reason)
+            hold = RELAY_HOLD if nxt[:parent_id] && RELAYED_KINDS.include?(question[:kind])
+            return Event.new(reason: reason_of(question), session_id: nxt[:id], key: key(nxt[:id], question[:id]), hold: hold)
+          end
+          card = nxt[:pending_card]
+          if card.is_a?(Hash) && card[:id] && card[:id] != prev&.dig(:pending_card, :id)
+            return Event.new(reason: "card", session_id: nxt[:id], key: card_key(nxt[:id], card[:id]), hold: nil)
+          end
+
+          turn_event(prev, nxt)
+        end
 
-          hold = RELAY_HOLD if nxt[:parent_id] && RELAYED_KINDS.include?(question[:kind])
-          Event.new(reason: reason, session_id: nxt[:id], key: key(nxt[:id], question[:id]), hold: hold)
+        # A top-level turn that ended since +prev+: failed, or done when it
+        # ran long or nobody watched it. A delegated child's turn is
+        # reported by its parent's.
+        def turn_event(prev, nxt)
+          turn = nxt[:last_turn]
+          return nil unless turn.is_a?(Hash) && turn["ended_at"]
+          return nil if turn["ended_at"] == prev&.dig(:last_turn, "ended_at") || nxt[:parent_id]
+
+          reason = case turn["outcome"]
+                   when "failed" then "failed"
+                   when "completed"
+                     "done" if seconds(turn) >= DONE_MIN_SECONDS || UNWATCHED_ORIGINS.include?(turn["origin"])
+                   end
+          reason && Event.new(reason: reason, session_id: nxt[:id], key: key(nxt[:id], turn["ended_at"]), hold: nil)
         end
 
         # The keys of what +prev+ had open and +nxt+ no longer has: its
-        # question answered (anywhere), gone or newly relayed; everything
-        # when the session is gone (+nxt+ nil).
+        # question answered (anywhere), gone or newly relayed, its card
+        # resolved or replaced; everything when the session is gone (+nxt+
+        # nil).
         # @return [Array<String>]
         def closed_keys(prev, nxt)
+          keys = []
           question = prev&.dig(:pending_question)
-          return [] unless question && question[:id]
-
-          now = nxt&.dig(:pending_question)
-          gone = now.nil? || now[:id] != question[:id] || (now[:relayed_to] && !question[:relayed_to])
-          gone ? [key(prev[:id], question[:id])] : []
+          if question.is_a?(Hash) && question[:id]
+            now = nxt&.dig(:pending_question)
+            gone = !now.is_a?(Hash) || now[:id] != question[:id] || (now[:relayed_to] && !question[:relayed_to])
+            keys << key(prev[:id], question[:id]) if gone
+          end
+          card = prev&.dig(:pending_card)
+          keys << card_key(prev[:id], card[:id]) if card.is_a?(Hash) && card[:id] && nxt&.dig(:pending_card, :id) != card[:id]
+          keys
         end
 
-        # Every key still open in +by_id+ (session id → summary): a
-        # pending question with an id, not relayed, of a reason P1 pushes.
-        # The rule push.js openPushKeys keeps, so the show's +open+ list,
-        # the page's cleanup and the badge agree.
+        # Every waiting key still open in +by_id+ (session id → summary): a
+        # pending question with an id, not relayed (any reason: a step-limit
+        # continue too), and a card with actions. The rule push.js
+        # openPushKeys keeps, so the show's +open+ list, the page's cleanup
+        # and the badge agree.
         # @return [Array<String>]
         def open_keys(by_id)
-          by_id.each_value.filter_map do |summary|
+          by_id.each_value.flat_map do |summary|
             question = summary[:pending_question]
-            next unless question.is_a?(Hash) && question[:id] && !question[:relayed_to]
-            next unless PUSHED.include?(reason_of(question))
-
-            key(summary[:id], question[:id])
+            card = summary[:pending_card]
+            keys = []
+            keys << key(summary[:id], question[:id]) if question.is_a?(Hash) && question[:id] && !question[:relayed_to]
+            keys << card_key(summary[:id], card[:id]) if card.is_a?(Hash) && card[:id]
+            keys
           end
         end
 
-        def key(session_id, question_id) = "#{session_id}:#{question_id}"
+        def key(session_id, id) = "#{session_id}:#{id}"
+        def card_key(session_id, card_id) = "#{session_id}:card:#{card_id}"
 
         # notify.js attentionText: the session's name (clipped) and the
         # reason, never the question or the command (a lock screen shows it).
@@ -92,7 +130,14 @@ module Samagotchi
         def text(summary, reason)
           name = (summary && [summary[:title], summary[:first_preview], summary[:last_prompt]].find { |v| present?(v) }) ||
                  "chi session"
-          [clip(name.to_s.strip, TITLE_MAX), BODIES.fetch(reason, "")]
+          body = reason == "done" ? "done in #{seconds(summary&.dig(:last_turn) || {}).round} s" : BODIES.fetch(reason, "")
+          [clip(name.to_s.strip, TITLE_MAX), body]
+        end
+
+        # notify.js Number(turn.seconds): anything that isn't a number is 0.
+        def seconds(turn)
+          value = turn["seconds"]
+          value.is_a?(Numeric) ? value.to_f : Float(value.to_s, exception: false) || 0.0
         end
 
         def present?(value) = !value.nil? && !value.to_s.strip.empty?

data/lib/samagotchi/web/push/client.rb

@@ -11,18 +11,25 @@ module Samagotchi
     module Push
       # One push to one device: the payload encrypted for its keys
       # (Crypto.encrypt), POSTed to its endpoint with chi web's VAPID header,
-      # and the push service's answer as a Result. No retry (P1). See
-      # docs/internals/web-push.md.
+      # and the push service's answer as a Result. It never retries itself:
+      # a Result says when a retry may help (+retry_after+), and the
+      # Notifier keeps it. See docs/internals/web-push.md.
       class Client
         OPEN_TIMEOUT = 5
         READ_TIMEOUT = 10
+        # A 429 or 5xx's Retry-After (delta-seconds) is taken up to this;
+        # without one (or as an HTTP date) a retry waits RETRY_DEFAULT.
+        RETRY_MAX = 60
+        RETRY_DEFAULT = 10
 
         # +status+ :ok (201/200/202), :gone (404/410: the device dropped
         # it), :bad_jwt (403 BadJwtToken: the push service refused chi's
         # VAPID token) or :failed; +code+ the HTTP status (nil when none
-        # came), +error+ a short word for a failure, +ms+ the call's time.
-        Result = Data.define(:status, :code, :ms, :error) do
-          def initialize(error: nil, **) = super
+        # came), +error+ a short word for a failure, +ms+ the call's time,
+        # +retry_after+ the seconds after which one retry may go (a 429 or
+        # 5xx; nil for anything else).
+        Result = Data.define(:status, :code, :ms, :error, :retry_after) do
+          def initialize(error: nil, retry_after: nil, **) = super
           def ok? = status == :ok
         end
 
@@ -93,7 +100,17 @@ module Samagotchi
                    when 403 then response.body.to_s.include?("BadJwtToken") ? :bad_jwt : :failed
                    else :failed
                    end
-          Result.new(status: status, code: code, ms: elapsed, error: status == :failed ? code.to_s : nil)
+          Result.new(status: status, code: code, ms: elapsed, error: status == :failed ? code.to_s : nil,
+                     retry_after: retry_after(response, code))
+        end
+
+        # The push service is busy (429) or failing (5xx): when to try once
+        # more.
+        def retry_after(response, code)
+          return nil unless code == 429 || (500..599).cover?(code)
+
+          value = response["Retry-After"].to_s.strip
+          value.match?(/\A\d+\z/) ? [value.to_i, RETRY_MAX].min : RETRY_DEFAULT
         end
 
         def ms(started) = ((@monotonic.call - started) * 1000).round

data/lib/samagotchi/web/push/notifier.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "time"
 require_relative "attention"
 require_relative "../../log"
 
@@ -10,9 +11,11 @@ module Samagotchi
       # chi web's one sender of pushes: a SessionHub subscriber that keeps
       # the summaries the page's trackAttention keeps (seeded by the
       # subscribe's snapshot, so what was open before never pushes), turns
-      # each new approval or question (Attention.for) into a show, and
-      # hands it to its own sender thread through a Queue; one answered
-      # anywhere (Attention.closed_keys) only cancels its show's hold.
+      # each new attention (Attention.for: a question, an approval, a
+      # step-limit continue, a card with actions, a failed or done turn)
+      # into a show, and hands it to its own sender thread through a Queue;
+      # one answered anywhere (Attention.closed_keys) only cancels its
+      # show's hold.
       #
       # Every push it sends shows a notification: WebKit removes a
       # subscription after a few pushes that show none (its silent-push
@@ -25,33 +28,57 @@ module Samagotchi
       # tick thread and on chi web's request threads (SessionHub#touch), so
       # it only enqueues; a push is a 0.5 s https call, made on the sender
       # thread. There a show waits its hold (HOLD, or the event's own) and
-      # is pushed only while still open, to every device subscribed on this
-      # run's public origin. See docs/internals/web-push.md.
+      # is pushed, a waiting one only while still open, to the devices
+      # subscribed on this run's public origin (a done turn only to those
+      # that asked for it), unless a chi web page is in front (Presence):
+      # then the owner is looking, and the key is never pushed. At most CAP
+      # shows an hour; a 429 or 5xx is retried once (Client::Result
+      # #retry_after) without the sender ever sleeping. Each key handled
+      # (pushed, skipped or capped) goes in the store's sent.json, so after
+      # a restart the seed pushes an approval asked meanwhile (open, under
+      # CATCH_UP old) and nothing pushed already. See
+      # docs/internals/web-push.md.
       class Notifier
         HOLD = 3.0
         # Waiting kinds: kept 12 h for an offline phone, delivered at once.
         SHOW_TTL = 12 * 3600
+        # A failed or done turn: stale soon, no need to wake the phone.
+        EVENT_TTL = 600
         # A show carries +open+ only while its JSON stays this small: one
         # aes128gcm record leaves 3993 bytes of plaintext under Web Push's
         # 4096 (86 header, 1 delimiter, 16 tag). Longer, it goes without
         # (and the worker cleans up nothing).
         OPEN_LIMIT = 3000
         STOP_JOIN = 2.0
+        # Shows (one event, however many devices) per rolling CAP_WINDOW.
+        CAP = 30
+        CAP_WINDOW = 3600
+        # A question open at a restart is pushed if it was asked this
+        # recently and isn't in sent.json.
+        CATCH_UP = 3600
 
         Show = Data.define(:attention, :title, :body, :at)
         Close = Data.define(:keys)
+        # One device's show, again at +at+ (the push service said when).
+        Retry = Data.define(:show, :sub_id, :at)
 
         # @param store [Store] the devices (and the key the client signs with)
         # @param client [#deliver] Client
         # @param origin [String] this run's public origin: only the
         #   subscriptions made on it are sent to
+        # @param presence [Presence, nil] the pages' reports (nil: nobody is
+        #   ever in front)
         # @param now [#call] monotonic seconds (specs move it)
-        def initialize(store:, client:, origin:, hold: HOLD, now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        # @param clock [#call] the Time now (a question's created_at)
+        def initialize(store:, client:, origin:, presence: nil, hold: HOLD,
+                       now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, clock: -> { Time.now })
           @store = store
           @client = client
           @origin = origin
+          @presence = presence
           @hold = hold
           @now = now
+          @clock = clock
           @queue = Queue.new
           # The sink's side (under @mutex): the last summary per session.
           @mutex = Mutex.new
@@ -60,6 +87,9 @@ module Samagotchi
           @early = []
           # The sender's side (its thread only, or #pump in a spec).
           @pending = {} # key → Show waiting its hold
+          @retries = {} # [key, device id] → Retry
+          @shown = [] # when each counted show went, oldest first
+          @capped_warned_at = nil
           @refused = false
           @thread = nil
           @handle = nil
@@ -97,10 +127,13 @@ module Samagotchi
         end
 
         # The seed: the summaries as the subscribe saw them. Events that came
-        # before it (newer than the snapshot) are applied after it.
+        # before it (newer than the snapshot) are applied after it. An open
+        # question asked under CATCH_UP ago that no earlier run handled
+        # (sent.json) is shown: it came while chi web was down.
         def seed(summaries)
           @mutex.synchronize do
             summaries.each { |summary| @by_id[summary[:id]] = summary if summary[:id] }
+            catch_up(summaries)
             @seeded = true
             @early.each { |event| notice(event) }
             @early.clear
@@ -142,6 +175,32 @@ module Samagotchi
           end
         end
 
+        # Cards carry no time: they seed as they are.
+        def catch_up(summaries)
+          sent = nil
+          at = @clock.call
+          summaries.each do |summary|
+            question = summary[:pending_question]
+            next unless summary[:id] && question.is_a?(Hash) && question[:id] && !question[:relayed_to]
+
+            asked = asked_at(question[:created_at])
+            next unless asked && at - asked < CATCH_UP
+
+            sent ||= @store.sent_keys
+            attention = Attention.for(nil, summary)
+            next if attention.nil? || sent.key?(attention.key)
+
+            Log.info(:web, "push_catch_up", kind: attention.reason)
+            enqueue_show(attention, summary)
+          end
+        end
+
+        def asked_at(text)
+          text.is_a?(String) ? Time.iso8601(text) : nil
+        rescue ArgumentError
+          nil
+        end
+
         def enqueue_show(attention, summary)
           title, body = Attention.text(summary, attention.reason)
           @queue << Show.new(attention: attention, title: title, body: body, at: @now.call)
@@ -149,7 +208,7 @@ module Samagotchi
 
         def run
           loop do
-            due = @pending.values.map { |show| due_at(show) }.min
+            due = (@pending.values.map { |show| due_at(show) } + @retries.values.map(&:at)).min
             wait = due && [due - @now.call, 0].max
             message = @queue.pop(timeout: wait)
             break if message == :stop
@@ -175,16 +234,70 @@ module Samagotchi
         def flush
           now = @now.call
           due = @pending.values.select { |show| due_at(show) <= now }
-          return if due.empty?
+          retries = @retries.values.select { |again| again.at <= now }
+          return if due.empty? && retries.empty?
 
           due.each { |show| @pending.delete(show.attention.key) }
+          retries.each { |again| @retries.delete([again.show.attention.key, again.sub_id]) }
           open = @mutex.synchronize { Attention.open_keys(@by_id) }
-          due.each do |show|
-            key = show.attention.key
-            next unless open.include?(key)
+          due.each { |show| send_show(show, open) if still_due?(show, open) }
+          retries.each { |again| send_retry(again, open) if still_due?(again.show, open) }
+        end
+
+        # A waiting show while its key is open; a failed or done turn's as
+        # is (nothing to answer).
+        def still_due?(show, open) = !Attention.waiting?(show.attention.reason) || open.include?(show.attention.key)
+
+        # A due show to its devices, unless a page is in front (the in-tab
+        # notification and badge have it) or the hour's cap is reached:
+        # either way the key is handled, never pushed later.
+        def send_show(show, open)
+          return if @refused
 
-            deliver(show_payload(show, open), kind: show.attention.reason)
+          subs = targets(show.attention.reason)
+          return if subs.empty?
+
+          key = show.attention.key
+          if @presence&.present?
+            Log.info(:web, "push_skipped", reason: "present", kind: show.attention.reason)
+            return handled(key)
           end
+          return handled(key) if capped?(show.attention.reason)
+
+          @shown << @now.call
+          handled(key) if deliver(subs, show_payload(show, open), show)
+        end
+
+        # The retry of one device's show: to that device, if it is still
+        # there; not counted against the cap again.
+        def send_retry(again, open)
+          return if @refused
+
+          sub = @store.for_origin(@origin).find { |candidate| candidate.id == again.sub_id }
+          return unless sub
+
+          handled(again.show.attention.key) if deliver([sub], show_payload(again.show, open), again.show, final: true)
+        end
+
+        # Over CAP shows in the last CAP_WINDOW: one warning per window.
+        def capped?(kind)
+          at = @now.call
+          @shown.shift while @shown.any? && at - @shown.first >= CAP_WINDOW
+          return false if @shown.size < CAP
+
+          if @capped_warned_at.nil? || at - @capped_warned_at >= CAP_WINDOW
+            @capped_warned_at = at
+            Log.warn(:web, "push_capped", cap: CAP, kind: kind,
+                                          echo: "[chi web] #{CAP} pushes in the last hour: holding the rest back")
+          end
+          true
+        end
+
+        # In sent.json: a restart's catch-up skips it.
+        def handled(key)
+          @store.mark_sent(key)
+        rescue SystemCallError => e
+          Log.warn(:web, "push_sent_unwritten", error: e.class.name)
         end
 
         def show_payload(show, open)
@@ -194,18 +307,37 @@ module Samagotchi
           JSON.generate(with_open).bytesize <= OPEN_LIMIT ? with_open : payload
         end
 
-        # @param kind [String] the reason, for the log line
+        # @param show [Show] its reason: the TTL and urgency, the log
+        #   line's kind
+        # @param final [Boolean] this is the one retry: a failure is final
         # @return [Boolean] whether any device took it
-        def deliver(payload, kind:)
-          return false if @refused
-
-          @store.for_origin(@origin).map do |sub|
-            result = @client.deliver(sub, payload, ttl: SHOW_TTL, urgency: "high")
-            record(sub, result, kind)
+        def deliver(subs, payload, show, final: false)
+          reason = show.attention.reason
+          waiting = Attention.waiting?(reason)
+          subs.map do |sub|
+            result = @client.deliver(sub, payload, ttl: waiting ? SHOW_TTL : EVENT_TTL, urgency: waiting ? "high" : "normal")
+            if result.retry_after && !final
+              retry_later(show, sub, result)
+              next false
+            end
+            record(sub, result, reason)
             result.ok?
           end.any?
         end
 
+        def retry_later(show, sub, result)
+          Log.info(:web, "push_retry", device: sub.id, code: result.code, ms: result.ms, kind: show.attention.reason,
+                                       after: result.retry_after)
+          @retries[[show.attention.key, sub.id]] = Retry.new(show: show, sub_id: sub.id, at: @now.call + result.retry_after)
+        end
+
+        # This origin's devices; a done turn only to those whose prefs ask
+        # for it (off by default).
+        def targets(reason)
+          subs = @store.for_origin(@origin)
+          reason == "done" ? subs.select(&:done?) : subs
+        end
+
         def record(sub, result, kind)
           fields = { device: sub.id, code: result.code, ms: result.ms, kind: kind }
           case result.status

data/lib/samagotchi/web/push/presence.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Web
+    module Push
+      # Whether the owner is at a chi web page now (the plan's D3: no push
+      # while they look): each page reports {page, front} (POST
+      # /api/push/presence; front = visible, focused and touched in the last
+      # 2 min) when that changes and every 30 s while front. The iPhone's
+      # service worker can't see the app in front, so this is decided here.
+      # In memory only (a restart forgets it: a page reports again within
+      # 30 s), shared by the route and the Notifier through Push::Runtime.
+      class Presence
+        # A front report counts this long: a page that stopped reporting (a
+        # closed laptop, a lost network) quiets the phone no longer.
+        TTL = 45.0
+        # Pages remembered (one per page load): the oldest report goes.
+        MAX_PAGES = 64
+        PAGE_MAX = 64
+
+        Report = Data.define(:front, :at)
+
+        # @param now [#call] monotonic seconds (specs move it)
+        def initialize(now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @now = now
+          @mutex = Mutex.new
+          @pages = {} # page id → Report, oldest first
+        end
+
+        # A page's report: +page+ its id for this load, +front+ whether the
+        # user is at it.
+        def report(page, front)
+          @mutex.synchronize do
+            @pages.delete(page)
+            @pages[page] = Report.new(front: front == true, at: @now.call)
+            @pages.shift while @pages.size > MAX_PAGES
+          end
+          nil
+        end
+
+        # Some page is in front, reported in the last TTL seconds.
+        def present?
+          at = @now.call
+          @mutex.synchronize { @pages.each_value.any? { |r| r.front && at - r.at < TTL } }
+        end
+
+        # A report's body as the page sends it: {page: id, front: bool}.
+        # @return [Array(String, Boolean), nil] nil when it isn't one
+        def self.parse(body)
+          return nil unless body.is_a?(Hash)
+
+          page, front = body.values_at("page", "front")
+          return nil unless page.is_a?(String) && !page.empty? && page.bytesize <= PAGE_MAX && [true, false].include?(front)
+
+          [page, front]
+        end
+      end
+    end
+  end
+end