k9o 1.3.0 → 1.5.0

data/lib/k9o/approvals.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module K9o
+  # Shared argument checks for the approvals, approval policy and schema namespaces. A bad value raises
+  # K9o::KError K9O_INVALID_FIELD_VALUE before any request is sent.
+  module ApprovalChecks
+    module_function
+
+    def invalid(message, context = {})
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: context)
+    end
+
+    def check_limit(limit)
+      return if limit.nil?
+      return if limit.is_a?(Integer) && limit >= 1 && limit <= 200
+
+      raise invalid('limit must be a whole number from 1 to 200', limit: limit)
+    end
+
+    def id_segment(value, what)
+      raise invalid("#{what} id must be a non-empty string") unless value.is_a?(String) && !value.empty?
+
+      ::URI.encode_www_form_component(value).gsub('+', '%20')
+    end
+
+    def reason!(reason)
+      raise invalid('reason is required and must be a non-empty string') unless reason.is_a?(String) && !reason.strip.empty?
+
+      reason
+    end
+
+    def predicate!(value, field)
+      raise invalid("#{field} must be a predicate object") unless value.is_a?(Hash)
+
+      value
+    end
+
+    def enum!(value, allowed, field)
+      text = value.is_a?(Symbol) ? value.to_s : value
+      return text if allowed.include?(text)
+
+      raise invalid("#{field} must be #{allowed.map { |a| "\"#{a}\"" }.join(', ')}", field.to_sym => value)
+    end
+  end
+
+  # True when a single-record write sent with +require_approval+ was queued for approval (HTTP 202) instead of
+  # applied. The queued answer carries +data+ = { 'id' => 'apr_...', 'status' => 'pending_approval', 'collection',
+  # 'operation', 'makerId', 'proposedPayload', 'targetRecordId' } and +meta.approval+ = { 'status' =>
+  # 'pending_approval' }; an +auto_approve+ policy applies the write and answers the plain row instead.
+  # Read the queued change in full with +approvals.get(id)+.
+  def self.queued_write?(result)
+    return false unless result.respond_to?(:data) && result.respond_to?(:meta)
+
+    approval = result.meta.respond_to?(:approval) ? result.meta.approval : nil
+    data = result.data
+    approval.is_a?(Hash) && approval['status'] == 'pending_approval' &&
+      data.is_a?(Hash) && data['status'] == 'pending_approval'
+  end
+
+  # Pending-change queue: k9o.approvals.*
+  #
+  #   list(status:, limit:, cursor:)       GET  /@<slug>/pending-approvals
+  #   get(id)                              GET  /@<slug>/pending-approvals/<id>
+  #   approve(id, reason:)                 POST /@<slug>/pending-approvals/<id>/approve
+  #   reject(id, reason:)                  POST /@<slug>/pending-approvals/<id>/reject
+  #   bulk(action:, criteria:, reason:)    POST /@<slug>/pending-approvals/bulk
+  #
+  # +list+ returns one page, newest first: +limit+ changes (1 to 200, default 50). While more remain,
+  # +meta.cursor.next+ is a string to pass back as +cursor:+; on the last page it is +nil+. +approve+ can answer 200
+  # with +status+ still +pending_approval+: the approval is recorded and more approvers are needed. +bulk+ answers
+  # HTTP 200 even when rows fail; read +failed+ and compare +affectedIds+ with what you intended.
+  class Approvals
+    # The comment thread on a pending change: +approvals.comments+.
+    attr_reader :comments
+
+    def initialize(config)
+      @config = config
+      @comments = ApprovalComments.new(config)
+    end
+
+    # One page of pending changes, newest first. +status+ is one of pending_approval, approved, rejected, expired or
+    # redeemed (omitted: all). Pass +meta.cursor.next+ from the previous page as +cursor+, with the same +status+
+    # and +limit+; an invalid cursor raises K9o::KError K9O_INVALID_CURSOR.
+    def list(status: nil, limit: nil, cursor: nil)
+      ApprovalChecks.check_limit(limit)
+      query = {}
+      query['status'] = status.to_s unless status.nil?
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor.to_s unless cursor.nil?
+      call('GET', path, query: query)
+    end
+
+    # One pending change. Members who are not queue admins can read only their own.
+    def get(id)
+      call('GET', path("/#{ApprovalChecks.id_segment(id, 'approval')}"))
+    end
+
+    # Approve a pending change. Read +status+ on the answer: +pending_approval+ means more approvers are needed.
+    def approve(id, reason: nil)
+      seg = ApprovalChecks.id_segment(id, 'approval')
+      call('POST', path("/#{seg}/approve"), body: reason.nil? ? {} : { 'reason' => reason })
+    end
+
+    # Reject a pending change. +reason+ is required and must not be empty.
+    def reject(id, reason:)
+      seg = ApprovalChecks.id_segment(id, 'approval')
+      call('POST', path("/#{seg}/reject"), body: { 'reason' => ApprovalChecks.reason!(reason) })
+    end
+
+    # Approve or reject every pending change matching +criteria+ (a predicate Hash). +reason+ is required to reject.
+    # The answer is HTTP 200 even when rows fail. +data+ holds +affectedIds+, +affectedCount+, +attestationId+,
+    # +action+, +reason+ and +failed+, a list of { 'id', 'code', 'reason' } (empty when none failed): compare
+    # +affectedIds+ with what you intended.
+    def bulk(action:, criteria:, reason: nil)
+      act = ApprovalChecks.enum!(action, %w[approve reject], 'action')
+      body = { 'action' => act, 'criteria' => ApprovalChecks.predicate!(criteria, 'criteria') }
+      if act == 'reject'
+        body['reason'] = ApprovalChecks.reason!(reason)
+      elsif !reason.nil?
+        body['reason'] = reason
+      end
+      res = call('POST', path('/bulk'), body: body)
+      res.data['failed'] = [] if res.data.is_a?(Hash) && !res.data['failed'].is_a?(Array)
+      res
+    end
+
+    private
+
+    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, 'approvals'), "pending-approvals#{tail}")
+    end
+  end
+
+  # Comments on a pending change: k9o.approvals.comments.*
+  #
+  #   add(pending_id, body:, visibility:)   POST /@<slug>/pending-approvals/<pending_id>/comments
+  #   list(pending_id, limit:, cursor:)     GET  /@<slug>/pending-approvals/<pending_id>/comments
+  #
+  # A comment is never a decision: it changes no status and counts toward no approval rule. It cannot be edited or
+  # deleted, so a correction is a new comment. Posting needs a session: a personal access token alone, or a service,
+  # workload or extension token, is refused with K9o::KError K9O_RBAC_DENY. Other errors: K9O_APPROVAL_COMMENT_NOT_ELIGIBLE
+  # (403, the caller may not post this comment), K9O_APPROVAL_COMMENT_CLOSED (409, the change is decided, expired or
+  # cancelled), K9O_INVALID_FIELD_VALUE (400) and K9O_NOT_FOUND (404, no such pending change).
+  class ApprovalComments
+    VISIBILITIES = %w[everyone approvers_only].freeze
+    BODY_MAX = 4000
+
+    # One page of comments: an Envelope whose +data+ is the Array of comments, oldest first, and whose +next_cursor+
+    # is the +cursor:+ of the next page, or +nil+ on the last page.
+    class Page < Envelope
+      attr_reader :next_cursor
+
+      def initialize(data:, meta:, next_cursor: nil)
+        super(data: data, meta: meta)
+        @next_cursor = next_cursor
+      end
+    end
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Post a comment. +body+ is plain text of 1 to 4000 characters. +visibility+ is required and fixed once posted:
+    # "everyone" reaches everyone who can read the change; "approvers_only" reaches only people eligible to decide it.
+    # Answers HTTP 201; +data+ is { 'id' (acm_...), 'caseId', 'authorId', 'visibility', 'body', 'createdAt' }.
+    def add(pending_id, body:, visibility:)
+      seg = ApprovalChecks.id_segment(pending_id, 'pending approval')
+      unless body.is_a?(String) && body.length >= 1 && body.length <= BODY_MAX
+        raise ApprovalChecks.invalid("body must be a string of 1 to #{BODY_MAX} characters")
+      end
+
+      payload = { 'body' => body, 'visibility' => ApprovalChecks.enum!(visibility, VISIBILITIES, 'visibility') }
+      call('POST', path(seg), body: payload)
+    end
+
+    # One page of the comments the caller may see, oldest first (+limit+ 1 to 200, default 50). While more remain,
+    # +next_cursor+ is a string to pass back as +cursor:+; on the last page it is +nil+. An invalid cursor raises
+    # K9o::KError K9O_INVALID_CURSOR.
+    def list(pending_id, limit: nil, cursor: nil)
+      seg = ApprovalChecks.id_segment(pending_id, 'pending approval')
+      ApprovalChecks.check_limit(limit)
+      query = {}
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor.to_s unless cursor.nil?
+      envelope = call('GET', path(seg), query: query, bare: true)
+      raw = envelope.data
+      data = raw.is_a?(Hash) && raw['data'].is_a?(Array) ? raw['data'] : []
+      Page.new(data: data, meta: envelope.meta, next_cursor: raw.is_a?(Hash) ? raw['nextCursor'] : nil)
+    end
+
+    private
+
+    def call(method, route, body: nil, query: nil, bare: false)
+      HttpTransport.request(config: @config, method: method, path: route, body: body, query: query, bare: bare)
+    end
+
+    def path(seg)
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'approvals'), "pending-approvals/#{seg}/comments")
+    end
+  end
+
+  # Approval policies: k9o.approval_policies.*
+  #
+  #   list                                              GET    /@<slug>/approval-policies
+  #   create(collection:, operation:, action:, predicate:)  POST   /@<slug>/approval-policies
+  #   delete(id)                                        DELETE /@<slug>/approval-policies/<id>
+  class ApprovalPolicies
+    COLLECTION_RE = /\A[a-zA-Z_][a-zA-Z0-9_]{0,62}\z/.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # All policies, oldest first. The first matching policy for a write decides.
+    def list
+      call('GET', path)
+    end
+
+    # Create a policy. Identical policies are not de-duplicated.
+    def create(collection:, operation:, action:, predicate:)
+      unless collection.is_a?(String) && COLLECTION_RE.match?(collection)
+        raise ApprovalChecks.invalid('collection must match ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$', collection: collection)
+      end
+
+      body = {
+        'collection' => collection,
+        'operation' => ApprovalChecks.enum!(operation, %w[insert update delete], 'operation'),
+        'action' => ApprovalChecks.enum!(action, %w[auto_approve queue], 'action'),
+        'predicate' => ApprovalChecks.predicate!(predicate, 'predicate')
+      }
+      call('POST', path, body: body)
+    end
+
+    # Delete a policy; the answer is { 'id' => ... }.
+    def delete(id)
+      call('DELETE', path("/#{ApprovalChecks.id_segment(id, 'policy')}"))
+    end
+
+    private
+
+    def call(method, route, body: nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body)
+    end
+
+    def path(tail = '')
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'approval_policies'), "approval-policies#{tail}")
+    end
+  end
+end

data/lib/k9o/audit.rb

@@ -4,6 +4,11 @@ module K9o
   # Project-plane audit log namespace — k9o.audit.*.
   # Distinct from k9o.org.audit_log.
   class Audit
+    TOPIC = 'audit.project'
+    TYPE_PATTERN = /\A[A-Za-z0-9_][A-Za-z0-9_.\-]*\z/.freeze
+    DEFAULT_REPLAY_LIMIT = 1000
+    EVENT_ID_PATTERN = /\Aevt_[0-9A-Za-z]{1,40}\z/.freeze
+
     def initialize(config)
       @config = config
     end
@@ -23,5 +28,150 @@ module K9o
       q['cursor'] = cursor unless cursor.nil?
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'audit-log'), query: q)
     end
+
+    # Live tail of the project's audit events: an Enumerator of { "auditEventId", "type", "actorType", "occurredAt",
+    # "outcome", "eventId" }. The first five are the audit event (read the full row with #query by event type and
+    # time); +eventId+ is the publisher's own id for the frame, which is not the +auditEventId+.
+    #
+    # +types+ is a list of audit event types: one type subscribes to +audit.project.<type>+, none to
+    # +audit.project.*+, several to +audit.project.*+ with the SDK keeping only those types. Needs ORG_OWNER,
+    # ORG_ADMIN, PROJECT_ADMIN or PROJECT_AUDITOR (re-checked every 60 seconds; others get 403 K9O_RBAC_DENY);
+    # extensions cannot subscribe. +warden.checkpoint+ events are not in the live tail: the audit log and #replay
+    # carry them.
+    #
+    # It is the same reconnecting reader as +realtime.subscribe+: it resumes with +Last-Event-ID+ (the frame's SSE
+    # +id+), drops events it already delivered (by the frame's +eventId+ and by +auditEventId+), ignores heartbeats
+    # and abandons a connection that has been silent for +Realtime.idle_timeout+ seconds. When the gateway says the
+    # position is lost (+event: resync+, action +replay-ledger+; audit streams cannot be resumed by sequence) the tail
+    # first reconnects fresh and buffers that connection's frames, then calls #replay after the last +auditEventId+ it
+    # delivered (page by page while there are more), yields the events it missed (they also carry +sequence+, and may
+    # include +warden.checkpoint+), calls +on_resync+ with the frame's hash, then yields the buffered and live frames,
+    # each event once. Nothing is lost: the connection is open before the replay runs. If it had delivered nothing yet
+    # it only reconnects (a new connection starts at the live head; a resync that opens a fresh connection is informational and ignored). Stop with +break+ or +first(n)+.
+    def tail(types: nil, on_resync: nil)
+      topic, keep = topic_for(types)
+      slug = Studio.require_project_slug(@config, 'audit')
+      catch_up = lambda do |_info, last_event|
+        last_event ? collect_replay(topic, last_event['auditEventId']) : []
+      end
+      decode = lambda do |data, frame|
+        payload = data.is_a?(Hash) ? data['payload'] : nil
+        next nil unless payload.is_a?(Hash) && payload['auditEventId'].is_a?(String)
+
+        event = {
+          'auditEventId' => payload['auditEventId'],
+          'type' => payload['type'].is_a?(String) ? payload['type'] : (data['eventType'] || frame[:event]),
+          'actorType' => payload['actorType'],
+          'occurredAt' => payload['occurredAt'],
+          'outcome' => payload['outcome']
+        }
+        event['eventId'] = data['eventId'] if data['eventId'].is_a?(String)
+        event
+      end
+      keys = lambda do |event, _frame|
+        [event['eventId'], event['auditEventId']].compact
+      end
+      cursor = lambda do |event, frame|
+        (frame && frame[:id]) || event['eventId']
+      end
+      Realtime.new(@config).feed(UrlGrammar.project_path(slug, 'realtime/subscribe'), { 'topic' => topic }, nil,
+                                 on_resync, decode: decode, keys: keys, cursor: cursor, accept: keep,
+                                 catch_up: catch_up, fresh_head_resync: true)
+    end
+
+    # POST /@<slug>/realtime/replay for the audit tail: a batch of past audit events in order, including
+    # +warden.checkpoint+. +topic+ is +audit.project.*+ (default) or +audit.project.<type>+. Give
+    # +after_audit_event_id+ (the last +auditEventId+ you received; unknown ids answer 400 K9O_INVALID_CURSOR) or
+    # +from_sequence+ (+after_audit_event_id+ wins when both are given); +until_sequence+ and +limit+ bound the batch (+limit+ is
+    # 1000 when omitted, up to 10,000). Needs the audit log's access.
+    #
+    # +data+ is the typed page { "events" => [event], "nextCursor", "hasMore" }; each event is { "auditEventId", "type",
+    # "actorType", "occurredAt", "outcome", "sequence" } (+sequence+ is a String, as the gateway sends it).
+    def replay(topic: "#{TOPIC}.*", after_audit_event_id: nil, from_sequence: nil, until_sequence: nil, limit: nil)
+      unless topic.is_a?(String) && (topic == TOPIC || topic.start_with?("#{TOPIC}."))
+        raise ApprovalChecks.invalid('topic must be audit.project.* or audit.project.<type>', topic: topic)
+      end
+      unless after_audit_event_id.nil? || (after_audit_event_id.is_a?(String) && EVENT_ID_PATTERN.match?(after_audit_event_id))
+        raise ApprovalChecks.invalid('after_audit_event_id must look like evt_<id>', after_audit_event_id: after_audit_event_id)
+      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['afterAuditEventId'] = after_audit_event_id unless after_audit_event_id.nil?
+      body['fromSequence'] = from_sequence unless from_sequence.nil?
+      body['untilSequence'] = until_sequence unless until_sequence.nil?
+      body['limit'] = limit.nil? ? DEFAULT_REPLAY_LIMIT : limit
+      slug = Studio.require_project_slug(@config, 'audit')
+      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
+
+    private
+
+    # [topic, filter or nil]
+    def topic_for(types)
+      list = types.nil? ? [] : Array(types).map { |t| t.is_a?(Symbol) ? t.to_s : t }
+      list.each do |t|
+        unless t.is_a?(String) && TYPE_PATTERN.match?(t)
+          raise ApprovalChecks.invalid('types must be audit event type names such as "data.write.access"', type: t)
+        end
+      end
+      list = list.uniq
+      return ["#{TOPIC}.*", nil] if list.empty?
+      return ["#{TOPIC}.#{list.first}", nil] if list.size == 1
+
+      ["#{TOPIC}.*", ->(event) { list.include?(event['type']) }]
+    end
+
+    # The replay answer with its events flattened to the tail's shape (+sequence+ kept).
+    def replay_page(data)
+      data = {} unless data.is_a?(Hash)
+      events = Array(data['events']).map { |e| flatten_replayed(e) }.compact
+      { 'events' => events, 'nextCursor' => data['nextCursor'], 'hasMore' => data['hasMore'] == true }
+    end
+
+    def flatten_replayed(raw)
+      return nil unless raw.is_a?(Hash)
+
+      payload = raw['payload'].is_a?(Hash) ? raw['payload'] : {}
+      return nil unless payload['auditEventId'].is_a?(String)
+
+      event = {
+        'auditEventId' => payload['auditEventId'],
+        'type' => payload['type'].is_a?(String) ? payload['type'] : raw['eventType'],
+        'actorType' => payload['actorType'],
+        'occurredAt' => payload['occurredAt'],
+        'outcome' => payload['outcome']
+      }
+      event['sequence'] = raw['sequence'] if raw.key?('sequence')
+      event
+    end
+
+    # Events after +last_id+ from the replay route, page after page while it says there are more. The route has no
+    # page cursor: each next page starts after the last event of the one before.
+    def collect_replay(topic, last_id)
+      out = []
+      cursor = last_id
+      loop do
+        data = replay(topic: topic, after_audit_event_id: cursor).data
+        events = data['events']
+        break if events.empty?
+
+        out.concat(events)
+        next_cursor = events.last['auditEventId']
+        break unless data['hasMore'] && next_cursor != cursor
+
+        cursor = next_cursor
+      end
+      out
+    end
   end
 end

data/lib/k9o/client.rb

@@ -3,8 +3,10 @@
 module K9o
   # The customer-facing client returned by K9o.create_client.
   class K9oClient
-    attr_reader :config, :projects, :gate, :studio, :compute, :realtime, :org,
-                :orgs, :migrations, :functions, :policies, :audit, :me, :kibo, :ai, :storage
+    include QueryMethods
+
+    attr_reader :config, :projects, :gate, :studio, :compute, :realtime, :streams, :org,
+                :approvals, :approval_policies, :schedules, :vectors, :metadata, :rampart, :custody, :end_users, :schema, :orgs, :migrations, :functions, :policies, :audit, :me, :kibo, :ai, :storage, :analytics, :rollups, :keys, :crypto
 
     def initialize(config)
       @config = config
@@ -13,6 +15,16 @@ module K9o
       @studio = Studio.new(config)
       @compute = Compute.new(config)
       @realtime = Realtime.new(config)
+      @streams = Streams.new(config)
+      @approvals = Approvals.new(config)
+      @approval_policies = ApprovalPolicies.new(config)
+      @schedules = Schedules.new(config)
+      @vectors = Vectors.new(config)
+      @metadata = Metadata.new(config)
+      @rampart = Rampart.new(config)
+      @custody = Custody.new(config)
+      @end_users = EndUsers.new(config)
+      @schema = Schema.new(config)
       @org = Org.new(config)
       @orgs = Orgs.new(config)
       @migrations = Migrations.new(config)
@@ -23,6 +35,10 @@ module K9o
       @kibo = KiboNamespace.new(config)
       @ai = Ai.new(config)
       @storage = Storage.new(config)
+      @analytics = Analytics.new(config)
+      @rollups = Rollups.new(config)
+      @keys = Keys.new(config)
+      @crypto = Crypto.new(config)
     end
 
     def from(collection)
@@ -45,12 +61,17 @@ module K9o
   # base_url is OPTIONAL. When omitted it defaults to the public-cloud platform host (a convenience only, never used
   # to parse a host). When the host is a platform host (+api.<apex>+ or +api-staging.<apex>+, any apex) and org_slug
   # is set, the org host +<org_slug>.<host>+ is composed. Any other host passes through unchanged.
-  def self.create_client(base_url: nil, api_key: nil, org_slug: nil, project_slug: nil, default_headers: {}, http_client: nil)
+  #
+  # expected_key_refs is optional: an Array of the key identifiers (from your own cloud configuration) your BYOK or HYOK
+  # key may be. It is checked here (see Crypto.check_expected_key_refs) and handed to the client core on every crypto call.
+  def self.create_client(base_url: nil, api_key: nil, org_slug: nil, project_slug: nil, default_headers: {}, http_client: nil,
+                         expected_key_refs: nil)
+    refs = Crypto.check_expected_key_refs(expected_key_refs)
     normalised = UrlGrammar.resolve_base_url(base_url, org_slug)
     config = HttpClientConfig.new(
       base_url: normalised,
       api_key: api_key, org_slug: org_slug, project_slug: project_slug,
-      default_headers: default_headers, http_client: http_client
+      default_headers: default_headers, http_client: http_client, expected_key_refs: refs
     )
     K9oClient.new(config)
   end