k9o 1.4.0 → 1.5.2

data/lib/k9o/rampart.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require_relative 'jcs'
+require_relative 'ed25519'
+
+module K9o
+  # Rampart: hosted classification of content. Advisory: it returns a verdict and a signed receipt and blocks
+  # nothing. Your code decides what to do with the verdict.
+  #
+  #   classify(input, label: nil)                  POST /@<slug>/rampart/classify
+  #   jwks                                          GET  /rampart/jwks  (public, no project prefix, no credential)
+  #   verify_receipt(receipt, input, **options)     checks the receipt locally and returns the verified verdict
+  #
+  # +classify+ answers an Envelope whose +data+ is { 'classification' => "clear" | "suspicious" | "malicious",
+  # 'riskScore', 'confidence' (both whole basis points, 0 to 10000), 'categories', 'calibrationVersion',
+  # 'classificationReceipt', 'projectId' }; the receipt is the string exactly as received. When the classifier is down the
+  # gateway answers 503 K9O_RAMPART_CLASSIFIER_UNAVAILABLE, raised as K9o::KError: there is no verdict and never a
+  # default pass. A long input is scored in overlapping windows (the highest injection score decides); past 16
+  # windows (about 6,000 tokens) the gateway answers 413 K9O_RAMPART_INPUT_TOO_LONG (context reason
+  # "rampart_input_too_long"), also raised as K9o::KError, with no verdict.
+  class Rampart
+    RECEIPT_TYP = 'k9o.rampart.classify.v1'
+    CLASSIFICATIONS = %w[clear suspicious malicious].freeze
+    DEFAULT_CLOCK_SKEW = 60
+    # The closed set of reasons verify_receipt refuses with, in the order it checks them.
+    REASONS = %i[malformed key_unknown alg typ signature issuer project_unknown project expired not_yet_valid
+                input_hash].freeze
+
+    # Raised by verify_receipt for every failure. +reason+ is one of REASONS; no verdict is returned with it.
+    # It is a K9o::KError, so +rescue K9o::KError+ catches it too.
+    class ReceiptRefusal < KError
+      attr_reader :reason
+
+      def initialize(reason, detail)
+        @reason = reason
+        super(code: 'K9O_RAMPART_RECEIPT_REFUSED', message: "#{reason}: #{detail}", context: { reason: reason.to_s })
+      end
+    end
+
+    # The claims of a receipt that passed every check. +windows+ is the number of windows the classifier scored (1 when
+    # the input fits one window), or nil when the receipt carries no such claim. Claims this SDK does not know are
+    # ignored.
+    Verdict = Struct.new(:classification, :risk_bp, :confidence_bp, :categories, :project_id, :calibration_version,
+                         :input_sha256, :issued_at, :expires_at, :kid, :windows, keyword_init: true)
+
+    def initialize(config)
+      @config = config
+      @lock = Mutex.new
+      @keys = nil
+      @feed_issuer = nil
+    end
+
+    # Classify +input+ (a Hash). +label+ is optional context for the classifier, 1 to 128 characters.
+    def classify(input, label: nil)
+      raise invalid('input must be a Hash') unless input.is_a?(Hash)
+      unless label.nil? || (label.is_a?(String) && label.length >= 1 && label.length <= 128)
+        raise invalid('label must be a String of 1 to 128 characters')
+      end
+
+      slug = Studio.require_project_slug(@config, 'rampart')
+      body = { 'input' => input }
+      body['label'] = label unless label.nil?
+      envelope = HttpTransport.request(config: @config, method: 'POST',
+                                       path: UrlGrammar.project_path(slug, 'rampart/classify'), body: body)
+      envelope
+    end
+
+    # The receipt key feed. +data+ is { 'keys' => [ { 'kid', 'kty', 'crv', 'x', ... } ], 'issuer' => "<issuer>/rampart" }.
+    # Public: sends no credential.
+    def jwks
+      HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.platform_path('rampart/jwks'),
+                            authenticated: false, bare: true)
+    end
+
+    # Verify a receipt against +input+ (the same Hash passed to classify) and return a Verdict read from the signed
+    # claims. +receipt+ is either the Envelope classify returned (it carries the receipt and its +projectId+) or the
+    # bare receipt String. Any failure raises ReceiptRefusal; there is never a partial verdict.
+    #
+    # Options:
+    #   key_set:    a key set you already fetched (the Hash from +jwks.data+, or its Array of keys). Without it the keys
+    #               are fetched from the feed, kept for the life of the client, and fetched once more on an unknown kid.
+    #   issuer:     the expected +iss+. Default: the +issuer+ the key feed advertises. With neither, the receipt is
+    #               refused with reason +issuer+.
+    #   project_id: the expected +project_id+. Default: the +projectId+ carried by the classify result passed in. A
+    #               bare receipt String with neither is refused with reason +project_unknown+.
+    #   clock_skew: seconds of tolerance on +iat+ and +exp+ (default 60).
+    #   clock:      a Time, a number of Unix seconds, or an object whose +call+ returns either. Default: the current time.
+    def verify_receipt(receipt, input, key_set: nil, issuer: nil, project_id: nil, clock_skew: DEFAULT_CLOCK_SKEW,
+                       clock: nil)
+      receipt, carried_project = unpack_result(receipt)
+      parts = split_receipt(receipt)
+      header = decode_json(parts[0], 'header')
+      claims = decode_json(parts[1], 'claims')
+      signature = decode_b64(parts[2], 'signature')
+
+      kid = header['kid']
+      raise refuse(:malformed, 'header has no kid') unless kid.is_a?(String) && !kid.empty?
+
+      jwk, feed_issuer = find_key(kid, key_set)
+      raise refuse(:alg, "alg must be EdDSA, got #{header['alg'].inspect}") unless header['alg'] == 'EdDSA'
+      raise refuse(:typ, "typ must be #{RECEIPT_TYP}, got #{header['typ'].inspect}") unless header['typ'] == RECEIPT_TYP
+
+      public_key = decode_b64(jwk['x'].to_s, 'key')
+      unless Ed25519.verify(public_key, "#{parts[0]}.#{parts[1]}", signature)
+        raise refuse(:signature, 'the signature does not match the receipt')
+      end
+
+      expected_issuer = issuer || feed_issuer
+      if expected_issuer.nil?
+        raise refuse(:issuer, 'no issuer is advertised by the key feed and none was given; pass issuer:')
+      end
+      unless claims['iss'] == expected_issuer
+        raise refuse(:issuer, "iss is #{claims['iss'].inspect}, expected #{expected_issuer}")
+      end
+
+      expected_project = project_id || carried_project
+      if expected_project.nil?
+        raise refuse(:project_unknown, 'no project id to compare with; pass the classify result or project_id:')
+      end
+      unless claims['project_id'].is_a?(String) && claims['project_id'] == expected_project
+        raise refuse(:project, 'the receipt was issued for a different project')
+      end
+
+      check_times(claims, clock_skew, clock)
+      unless claims['input_sha256'] == input_digest(input)
+        raise refuse(:input_hash, 'the receipt does not attest this input')
+      end
+
+      build_verdict(claims, kid)
+    end
+
+    # SHA-256 of the canonical form (see Jcs) of +input+, as lowercase hex.
+    def input_digest(input)
+      raise ReceiptRefusal.new(:input_hash, 'input must be a Hash') unless input.is_a?(Hash)
+
+      Digest::SHA256.hexdigest(Jcs.canonical_bytes(input))
+    rescue Jcs::Error => e
+      raise ReceiptRefusal.new(:input_hash, "the input cannot be canonicalised: #{e.message}")
+    end
+
+    private
+
+    def invalid(message)
+      ApprovalChecks.invalid(message, {})
+    end
+
+    def refuse(reason, detail)
+      ReceiptRefusal.new(reason, detail)
+    end
+
+    # [receipt String, projectId carried by a classify result or nil].
+    def unpack_result(value)
+      data = value.respond_to?(:data) ? value.data : value
+      return [value, nil] unless data.is_a?(Hash)
+
+      carried = data['projectId']
+      [data['classificationReceipt'], carried.is_a?(String) && !carried.empty? ? carried : nil]
+    end
+
+    def split_receipt(receipt)
+      raise refuse(:malformed, 'receipt must be a String') unless receipt.is_a?(String)
+
+      parts = receipt.split('.', -1)
+      raise refuse(:malformed, 'receipt must have three dot-separated parts') unless parts.size == 3 && parts.none?(&:empty?)
+
+      parts
+    end
+
+    def decode_b64(text, what)
+      raise refuse(:malformed, "#{what} is not base64url") unless text.match?(/\A[A-Za-z0-9_-]+\z/)
+
+      padded = text.tr('-_', '+/')
+      padded += '=' * ((4 - (padded.length % 4)) % 4)
+      padded.unpack1('m0')
+    rescue ArgumentError
+      raise refuse(:malformed, "#{what} is not base64url")
+    end
+
+    def decode_json(text, what)
+      parsed = JSON.parse(decode_b64(text, what).force_encoding(Encoding::UTF_8))
+      raise refuse(:malformed, "#{what} is not a JSON object") unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError, EncodingError
+      raise refuse(:malformed, "#{what} is not JSON")
+    end
+
+    def normalise_keys(key_set)
+      list = key_set.is_a?(Hash) ? (key_set['keys'] || key_set[:keys]) : key_set
+      raise refuse(:key_unknown, 'the key set has no keys') unless list.is_a?(Array)
+
+      list.each_with_object({}) do |jwk, out|
+        next unless jwk.is_a?(Hash)
+
+        jwk = jwk.transform_keys(&:to_s)
+        out[jwk['kid']] = jwk if jwk['kid'].is_a?(String)
+      end
+    end
+
+    # [the key for +kid+, the issuer the feed advertises or nil].
+    def find_key(kid, key_set)
+      keys, advertised = if key_set.nil?
+                           cached_feed(kid)
+                         else
+                           [normalise_keys(key_set), feed_issuer_of(key_set)]
+                         end
+      jwk = keys[kid]
+      raise refuse(:key_unknown, "no key with kid #{kid.inspect} in the key feed") if jwk.nil?
+      unless jwk['kty'] == 'OKP' && jwk['crv'] == 'Ed25519' && jwk['x'].is_a?(String)
+        raise refuse(:key_unknown, "key #{kid.inspect} is not an Ed25519 key")
+      end
+
+      [jwk, advertised]
+    end
+
+    def feed_issuer_of(feed)
+      return nil unless feed.is_a?(Hash)
+
+      value = feed['issuer'] || feed[:issuer]
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
+    # Keys and issuer kept for the client's life; one refetch when the kid is not among the keys.
+    def cached_feed(kid)
+      @lock.synchronize do
+        if @keys.nil? || !@keys.key?(kid)
+          feed = jwks.data
+          @keys = normalise_keys(feed)
+          @feed_issuer = feed_issuer_of(feed)
+        end
+        [@keys, @feed_issuer]
+      end
+    end
+
+    def now_seconds(clock)
+      value = clock.respond_to?(:call) ? clock.call : clock
+      value = Time.now if value.nil?
+      value.to_f
+    end
+
+    def check_times(claims, skew, clock)
+      iat = claims['iat']
+      exp = claims['exp']
+      unless iat.is_a?(Numeric) && exp.is_a?(Numeric)
+        raise refuse(:malformed, 'iat and exp must be numbers')
+      end
+
+      now = now_seconds(clock)
+      raise refuse(:expired, 'the receipt has expired') if now > exp + skew
+      raise refuse(:not_yet_valid, 'the receipt is issued in the future') if iat > now + skew
+    end
+
+    def build_verdict(claims, kid)
+      cls = claims['classification']
+      risk = claims['risk_bp']
+      conf = claims['confidence_bp']
+      cats = claims['categories']
+      ok = CLASSIFICATIONS.include?(cls) &&
+           [risk, conf].all? { |n| n.is_a?(Integer) && n >= 0 && n <= 10_000 } &&
+           cats.is_a?(Array) && cats.all?(String) &&
+           claims['calibration_version'].is_a?(String) && claims['input_sha256'].is_a?(String)
+      raise refuse(:malformed, 'the signed claims are not a verdict') unless ok
+
+      Verdict.new(classification: cls, risk_bp: risk, confidence_bp: conf, categories: cats.dup.freeze,
+                  project_id: claims['project_id'], calibration_version: claims['calibration_version'],
+                  input_sha256: claims['input_sha256'], issued_at: Time.at(claims['iat']).utc,
+                  expires_at: Time.at(claims['exp']).utc, kid: kid,
+                  windows: claims['windows'].is_a?(Integer) && claims['windows'] >= 1 ? claims['windows'] : nil)
+    end
+  end
+end

data/lib/k9o/realtime.rb

@@ -3,30 +3,281 @@
 module K9o
   # Realtime Subscriptions namespace.
   #
-  # Transport: SSE over GET /@<slug>/realtime/subscribe. The gateway serves no WebSocket upgrade and no durable
-  # replay, so neither is offered; after an `event: resync` frame the caller re-reads current state from the data
-  # plane and resubscribes. #subscribe returns an Enumerator iterated via `.each`.
+  # Transport: SSE over GET /@<slug>/realtime/subscribe. The gateway closes each stream after at most 300 seconds
+  # and sends a +:hb+ comment every 15 seconds on a quiet feed. #subscribe returns an Enumerator that reconnects
+  # with +Last-Event-ID+, drops events it has already delivered and, when the gateway reports that the position
+  # is lost (+event: resync+), calls +on_resync+ and continues from a fresh connection.
   class Realtime
+    @idle_timeout = 45
+    @max_backoff = 30
+    @sleeper = ->(seconds) { sleep(seconds) }
+    DEFAULT_RETRY_MS = 1000
+    SEEN_LIMIT = 1024
+
+    class << self
+      # Seconds without any bytes (events, comments, heartbeats) after which a connection is abandoned.
+      attr_accessor :idle_timeout
+      # Longest reconnect delay in seconds.
+      attr_accessor :max_backoff
+      # Callable taking seconds; replaceable in tests.
+      attr_accessor :sleeper
+    end
+
     def initialize(config)
       @config = config
     end
 
     # Subscribe via SSE; returns an Enumerator yielding event hashes
-    # { 'topic', 'eventType', 'payload', 'occurredAt' } (the gateway's spelling). Control frames such as `resync`
-    # carry no +eventType+ and are skipped.
-    def subscribe(topic, filter: nil)
+    # { 'topic', 'eventType', 'payload', 'occurredAt', 'eventId' } (the gateway's spelling).
+    #
+    # The enumerator reconnects when the stream ends or fails, sending +Last-Event-ID+, and drops events whose
+    # +eventId+ it has already delivered (delivery is at-least-once). A client error (4xx) is raised once as a
+    # K9o::KError; server errors and network errors are retried with a capped backoff (30 seconds at most).
+    # An +event: resync+ frame is not yielded: +on_resync+ (a callable, may be nil) receives its
+    # { 'reason', 'action' } hash, then a fresh connection starts without +Last-Event-ID+. Stop by leaving the
+    # +each+ block (break) or by taking a finite number (+first(n)+).
+    def subscribe(topic, filter: nil, on_resync: nil)
       slug = Studio.require_project_slug(@config, 'realtime')
       q = { 'topic' => topic }
       q['filter'] = JSON.dump(filter) if filter
-      frames = HttpTransport.stream_sse(config: @config, method: 'GET',
-                                        path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
+      feed(UrlGrammar.project_path(slug, 'realtime/subscribe'), q, nil, on_resync)
+    end
+
+    # POST /@<slug>/realtime/replay: a batch of past events for +topic+ (required, the same topic strings as
+    # #subscribe, 1 to 200 characters). +from_sequence+ and +until_sequence+ (whole numbers, 0 or more) bound the
+    # range; +limit+ (1 to 10,000) caps the batch, and the gateway's own default applies when omitted.
+    #
+    # Answers an Envelope whose +data+ is { "events" => [event], "nextCursor", "hasMore" } and, when the gateway
+    # says the topic has no stored history, "resync" => "reread-source" (re-read the current state instead). Each
+    # event is a Hash as the gateway sent it, in the spelling #subscribe yields ("topic", "eventType", "payload",
+    # "occurredAt", "eventId"; an event from the audit log also carries "sequence"). A 4xx raises K9o::KError.
+    def replay(topic, from_sequence: nil, until_sequence: nil, limit: nil)
+      unless topic.is_a?(String) && !topic.empty? && topic.length <= 200
+        raise ApprovalChecks.invalid('topic must be a realtime topic string of 1 to 200 characters', topic: topic)
+      end
+      { from_sequence: from_sequence, until_sequence: until_sequence }.each do |name, value|
+        next if value.nil? || (value.is_a?(Integer) && value >= 0)
+
+        raise ApprovalChecks.invalid("#{name} must be a whole number, 0 or more", name => value)
+      end
+      unless limit.nil? || (limit.is_a?(Integer) && limit >= 1 && limit <= 10_000)
+        raise ApprovalChecks.invalid('limit must be a whole number from 1 to 10000', limit: limit)
+      end
+
+      body = { 'topic' => topic }
+      body['fromSequence'] = from_sequence unless from_sequence.nil?
+      body['untilSequence'] = until_sequence unless until_sequence.nil?
+      body['limit'] = limit unless limit.nil?
+      slug = Studio.require_project_slug(@config, 'realtime')
+      envelope = HttpTransport.request(config: @config, method: 'POST',
+                                       path: UrlGrammar.project_path(slug, 'realtime/replay'), body: body)
+      Envelope.new(data: replay_page(envelope.data), meta: envelope.meta)
+    end
+
+    # The reconnecting reader behind #subscribe, Metadata#subscribe, Rollups#subscribe and Audit#tail.
+    # +initial_query+ is added to the query of the first connection only, and only while the feed has no position of
+    # its own.
+    #
+    # Frame options. By default a frame's JSON data is the event: +type_key+ is the field it must carry as a String
+    # to count (nil accepts any JSON object) and +id_key+ names the event (the frame's SSE +id+ when absent).
+    # A feed whose frames wrap the event passes +decode+, a callable taking the parsed data and the frame
+    # ({ event:, id:, data:, retry: }) and answering the event Hash to deliver, or nil to skip the frame.
+    # +keys+ (callable taking the event and the frame, or nil for a caught-up event) answers the strings that identify
+    # the event for de-duplication; +cursor+ (same arguments) answers the value sent as +Last-Event-ID+ when the
+    # connection is reopened (default: the first key). +accept+ (a callable) drops events after they have been counted
+    # as delivered. +catch_up+ (a callable taking the resync hash and the last delivered event, or nil, and answering an
+    # Array of events) is called on a resync instead of clearing the memory of delivered events. The feed first opens a
+    # fresh connection (no +Last-Event-ID+) and buffers its frames, then calls +catch_up+ (only when an event had been
+    # delivered), yields its events, then the buffered and live frames, all de-duplicated through +keys+; an event
+    # published while +catch_up+ ran is on the fresh connection, so nothing is lost. A fresh connection that is itself
+    # answered with a resync backs off before the next attempt. A resync that is the first
+    # data of a connection opened with no position (neither +Last-Event-ID+ nor the +initial_query+ start position) is informational and ignored (the stream goes on); this is the
+    # default (+fresh_head_resync: true+). A resync after data, or on a connection that sent a position, is a lost position.
+    def feed(route, q, initial_query, on_resync, type_key: 'eventType', id_key: 'eventId', accept: nil, catch_up: nil,
+             decode: nil, keys: nil, cursor: nil, fresh_head_resync: true)
+      keys ||= lambda do |event, frame|
+        id = event[id_key].is_a?(String) ? event[id_key] : (frame && frame[:id])
+        id ? [id] : []
+      end
+      remember = lambda do |seen, ks|
+        ks.each do |k|
+          seen[k] = true
+          seen.shift while seen.size > SEEN_LIMIT
+        end
+      end
       Enumerator.new do |yielder|
-        frames.each do |event|
-          yielder << event if event.is_a?(Hash) && event['eventType'].is_a?(String)
+        use_initial = true
+        last_id = nil
+        last_event = nil
+        seen = {}
+        retry_ms = DEFAULT_RETRY_MS
+        failures = 0
+        resyncs = 0
+        buffered = nil
+        loop do
+          headers = last_id ? { 'Last-Event-ID' => last_id } : nil
+          resync_info = nil
+          failed = false
+          got_event = false
+          seen_resync = false
+          sent_position = !last_id.nil?
+          begin
+            query = use_initial && last_id.nil? && initial_query ? q.merge(initial_query) : q
+            sent_position ||= !query.equal?(q)
+            use_initial = false
+            frames = buffered || HttpTransport.stream_sse(config: @config, method: 'GET', path: route, query: query,
+                                                          headers: headers, idle_timeout: self.class.idle_timeout, raw: true)
+            buffered = nil
+            catch(:resync) do
+              frames.each do |frame|
+                retry_ms = frame[:retry] if frame[:retry]
+                next if frame[:data].nil? && frame[:event].nil?
+
+                if frame[:event] == 'resync'
+                  # Informational: a fresh connection (no Last-Event-ID sent) opens with the live head's resync;
+                  # events follow on the same stream, so keep reading it.
+                  if fresh_head_resync && !sent_position && !got_event && !seen_resync
+                    seen_resync = true
+                    next
+                  end
+
+                  info = parse(frame[:data])
+                  resync_info = info.is_a?(Hash) ? info : {}
+                  throw :resync
+                end
+                data = parse(frame[:data])
+                if decode
+                  event = decode.call(data, frame)
+                  next unless event.is_a?(Hash)
+                else
+                  event = data
+                  next unless event.is_a?(Hash) && (type_key.nil? || event[type_key].is_a?(String))
+                end
+
+                failures = 0
+                resyncs = 0
+                got_event = true
+                ks = keys.call(event, frame)
+                next if ks.any? { |k| seen.key?(k) }
+
+                remember.call(seen, ks)
+                pos = cursor ? cursor.call(event, frame) : ks.first
+                last_id = pos if pos
+                last_event = event
+                yielder << event if accept.nil? || accept.call(event)
+              end
+            end
+          rescue KError => e
+            raise if e.status && e.status < 500
+
+            failed = true
+          ensure
+            frames.close if frames.respond_to?(:close)
+          end
+
+          if resync_info
+            failures = 0
+            use_initial = false
+            if catch_up
+              resyncs += 1
+              last_id = nil
+              delay = resyncs >= 2 ? [retry_ms / 1000.0 * (2**(resyncs - 2)), self.class.max_backoff].min : retry_ms / 1000.0
+              self.class.sleeper.call(delay) if delay.positive?
+              if last_event
+                buffered = BufferedStream.new(HttpTransport.stream_sse(config: @config, method: 'GET', path: route,
+                                                                        query: q, idle_timeout: self.class.idle_timeout,
+                                                                        raw: true))
+                begin
+                  buffered.wait_open
+                  Array(catch_up.call(resync_info, last_event)).each do |event|
+                    next unless event.is_a?(Hash)
+
+                    ks = keys.call(event, nil)
+                    next if ks.any? { |k| seen.key?(k) }
+
+                    remember.call(seen, ks)
+                    last_event = event
+                    yielder << event if accept.nil? || accept.call(event)
+                  end
+                rescue Exception # rubocop:disable Lint/RescueException
+                  buffered.close
+                  buffered = nil
+                  raise
+                end
+              end
+              on_resync&.call(resync_info)
+              next
+            end
+            last_id = nil
+            last_event = nil
+            seen.clear
+            on_resync&.call(resync_info)
+            next
+          end
+          failures += 1 if failed
+          delay = failed ? [retry_ms / 1000.0 * (2**(failures - 1)), self.class.max_backoff].min : retry_ms / 1000.0
+          self.class.sleeper.call(delay) if delay.positive?
+        end
+      end
+    end
+
+    # Reads an SSE frame enumerator on a thread into a queue, so the connection stays open (and its frames are kept)
+    # while something else runs. +each+ replays the kept frames, then the live ones; a failure is raised from +each+.
+    class BufferedStream
+      def initialize(source)
+        @queue = Queue.new
+        @head = nil
+        @thread = Thread.new do
+          begin
+            source.each { |frame| @queue << [:frame, frame] }
+            @queue << [:end]
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            @queue << [:error, e]
+          end
+        end
+        @thread.report_on_exception = false
+      end
+
+      # Blocks until the connection answered (first frame), failed or ended.
+      def wait_open
+        @head ||= @queue.pop
+      end
+
+      def each
+        loop do
+          msg = @head || @queue.pop
+          @head = nil
+          case msg.first
+          when :frame then yield msg[1]
+          when :error then raise msg[1]
+          else break
+          end
         end
       end
+
+      def close
+        @thread.kill
+      end
+    end
+
+    private
+
+    def replay_page(data)
+      data = {} unless data.is_a?(Hash)
+      page = { 'events' => Array(data['events']).select { |e| e.is_a?(Hash) },
+               'nextCursor' => data['nextCursor'], 'hasMore' => data['hasMore'] == true }
+      page['resync'] = data['resync'] if data['resync'].is_a?(String)
+      page
     end
 
+    def parse(text)
+      JSON.parse(text.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+
+    public
+
     module Topic
       module_function
 

data/lib/k9o/schedules.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module K9o
+  # Schedules: k9o.schedules.* run a function on a timetable (cron). They need the project admin role to change.
+  #
+  #   list(status:, function_name:, limit:, cursor:)    GET    /@<slug>/forge/schedules
+  #   get(id)                                           GET    /@<slug>/forge/schedules/<id>
+  #   create(function_name:, schedule_expression:, ...) POST   /@<slug>/forge/schedules
+  #   update(id, **fields)                              PATCH  /@<slug>/forge/schedules/<id>
+  #   delete(id)                                        DELETE /@<slug>/forge/schedules/<id>   (204, no body)
+  #   runs(id, limit:, cursor:)                         GET    /@<slug>/forge/schedules/<id>/runs
+  #   run_now(id)                                       POST   /@<slug>/forge/schedules/<id>/run-now   (202)
+  #
+  # Lists are cursor-paginated, newest first: pass +meta.cursor.next+ of one page as +cursor:+ of the next, until it
+  # is nil. A schedule interval under 5 minutes is rejected with 400 K9O_INVALID_FIELD_VALUE (field schedule_expression), on every plan.
+  class Schedules
+    CATCHUP_POLICIES = %w[skip run_once run_all].freeze
+    STATUSES = %w[active paused].freeze
+    UPDATE_FIELDS = %i[schedule_expression schedule_timezone catchup_policy status enabled log_ok_invocations].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Schedules, newest first. +status+ is active or paused; +function_name+ keeps one function's schedules;
+    # +limit+ is 1 to 200 (the gateway defaults to 50).
+    def list(status: nil, function_name: nil, limit: nil, cursor: nil)
+      ApprovalChecks.check_limit(limit)
+      query = {}
+      query['status'] = ApprovalChecks.enum!(status, STATUSES, 'status') unless status.nil?
+      query['function_name'] = function_name unless function_name.nil?
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor unless cursor.nil?
+      call('GET', path, query: query)
+    end
+
+    def get(id)
+      call('GET', path(one(id)))
+    end
+
+    # Create a schedule; answers 201 with the schedule. +schedule_expression+ is a five-field cron or one of @yearly,
+    # @annually, @monthly, @weekly, @daily, @midnight, @hourly (stored and returned expanded). +schedule_timezone+
+    # defaults to UTC; +catchup_policy+ to skip.
+    def create(function_name:, schedule_expression:, schedule_timezone: nil, catchup_policy: nil, collection: nil,
+               enabled: nil, log_ok_invocations: nil)
+      body = { 'functionName' => function_name, 'scheduleExpression' => schedule_expression }
+      body['scheduleTimezone'] = schedule_timezone unless schedule_timezone.nil?
+      body['catchupPolicy'] = ApprovalChecks.enum!(catchup_policy, CATCHUP_POLICIES, 'catchup_policy') unless catchup_policy.nil?
+      body['collection'] = collection unless collection.nil?
+      body['enabled'] = enabled unless enabled.nil?
+      body['logOkInvocations'] = log_ok_invocations unless log_ok_invocations.nil?
+      call('POST', path, body: body)
+    end
+
+    # Change a schedule; send at least one of +schedule_expression+, +schedule_timezone+, +catchup_policy+,
+    # +status+ ('paused' stops it, 'active' resumes it), +enabled+, +log_ok_invocations+. The function cannot change.
+    def update(id, **fields)
+      unknown = fields.keys - UPDATE_FIELDS
+      raise ApprovalChecks.invalid("unknown field: #{unknown.join(', ')}") unless unknown.empty?
+      raise ApprovalChecks.invalid("patch needs at least one of: #{UPDATE_FIELDS.join(', ')}") if fields.empty?
+
+      seg = one(id)
+      body = {}
+      body['scheduleExpression'] = fields[:schedule_expression] if fields.key?(:schedule_expression)
+      body['scheduleTimezone'] = fields[:schedule_timezone] if fields.key?(:schedule_timezone)
+      if fields.key?(:catchup_policy)
+        body['catchupPolicy'] = ApprovalChecks.enum!(fields[:catchup_policy], CATCHUP_POLICIES, 'catchup_policy')
+      end
+      body['status'] = ApprovalChecks.enum!(fields[:status], STATUSES, 'status') if fields.key?(:status)
+      body['enabled'] = fields[:enabled] if fields.key?(:enabled)
+      body['logOkInvocations'] = fields[:log_ok_invocations] if fields.key?(:log_ok_invocations)
+      call('PATCH', path(seg), body: body)
+    end
+
+    # Delete a schedule. Answers 204, so +data+ is nil.
+    def delete(id)
+      call('DELETE', path(one(id)))
+    end
+
+    # The schedule's runs, newest first, one page at a time.
+    def runs(id, limit: nil, cursor: nil)
+      ApprovalChecks.check_limit(limit)
+      seg = one(id)
+      query = {}
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor unless cursor.nil?
+      call('GET', path("#{seg}/runs"), query: query)
+    end
+
+    # Start one run now, outside the timetable. Answers 202; +data+ is the body exactly as the gateway sent it.
+    def run_now(id)
+      call('POST', path("#{one(id)}/run-now"))
+    end
+
+    private
+
+    def one(id)
+      "/#{ApprovalChecks.id_segment(id, 'schedule')}"
+    end
+
+    def call(method, route, body: nil, query: nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body, query: query)
+    end
+
+    def path(tail = '')
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'schedules'), "forge/schedules#{tail}")
+    end
+  end
+end