k9o 1.2.0-aarch64-linux → 1.5.0-aarch64-linux

data/lib/k9o/data.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module K9o
   # Data-plane DSL.
   #
@@ -17,12 +19,22 @@ module K9o
       SelectBuilder.new(@config, @collection)
     end
 
-    def insert(record)
+    # Insert one record. With +require_approval: true+ the write is sent as +?requireApproval=true+ and waits for
+    # approval; the answer is then a queued change (HTTP 202) or, when an +auto_approve+ policy covers the write,
+    # the inserted row. Tell them apart with K9o.queued_write?.
+    def insert(record = nil, require_approval: false, **fields)
+      record = fields if record.nil? # a braceless hash literal arrives as keywords on Ruby 3
       HttpTransport.request(
-        config: @config, method: 'POST', path: FromBuilder.collection_path(@config, @collection), body: record
+        config: @config, method: 'POST', path: FromBuilder.collection_path(@config, @collection), body: record,
+        query: FromBuilder.approval_query(require_approval)
       )
     end
 
+    # +{ 'requireApproval' => 'true' }+ for a write that asks to be queued, +nil+ (no query) otherwise.
+    def self.approval_query(require_approval)
+      require_approval ? { 'requireApproval' => 'true' } : nil
+    end
+
     def update(patch)
       UpdateBuilder.new(@config, @collection, patch)
     end
@@ -57,6 +69,7 @@ module K9o
       @collection = collection
       @filters = []
       @limit_val = nil
+      @require_approval = false
       @cursor_val = nil
       @count_mode = nil
     end
@@ -113,13 +126,104 @@ module K9o
   end
 
   class SelectBuilder < BaseBuilder
+    SEARCH_COLUMN = /\A[a-zA-Z_][a-zA-Z0-9_]{0,62}\z/.freeze
+    SEARCH_LANGUAGE = /\A[a-zA-Z_]+\z/.freeze
+    TEXT_TYPES = %w[plain phrase websearch].freeze
+    VECTOR_METRICS = %w[cosine euclidean dot].freeze
+
+    def initialize(config, collection)
+      super
+      @search = {}
+      @vector = nil
+    end
+
+    # Full-text search over one text column. +type+ is "plain", "phrase" or "websearch".
+    def text_search(column, query, language: 'english', type: 'plain')
+      check_search_column(column)
+      raise search_error('text search query must be a non-empty string') unless query.is_a?(String) && !query.empty?
+      unless language.is_a?(String) && language.match?(SEARCH_LANGUAGE)
+        raise search_error('text search language must be letters and underscores only')
+      end
+
+      type = type.to_s
+      raise search_error("text search type must be one of #{TEXT_TYPES.join(', ')}") unless TEXT_TYPES.include?(type)
+
+      @search.delete('textSearchLanguage')
+      @search.delete('textSearchType')
+      @search['textSearch'] = "#{column}:#{query}"
+      @search['textSearchLanguage'] = language unless language == 'english'
+      @search['textSearchType'] = type unless type == 'plain'
+      self
+    end
+
+    # Nearest-neighbour search over one vector column; results come back closest first. The embedding travels in
+    # the request body (POST data/<collection>/search), so a real embedding of any length works.
+    # +metric+ is "cosine", "euclidean" or "dot"; +limit+ is 1 to 1000 (server default 10). The rows returned are
+    # the smaller of this +limit+ and the query's +limit+ (default 50): to get N rows set both.
+    # It cannot be combined with +text_search+.
+    def vector_search(column, embedding, metric: 'cosine', limit: nil)
+      check_search_column(column)
+      unless embedding.is_a?(Array) && !embedding.empty? &&
+             embedding.all? { |v| v.is_a?(Integer) || (v.is_a?(Float) && v.finite?) }
+        raise search_error('embedding must be a non-empty array of finite numbers')
+      end
+
+      metric = metric.to_s
+      raise search_error("vector metric must be one of #{VECTOR_METRICS.join(', ')}") unless VECTOR_METRICS.include?(metric)
+      unless limit.nil? || (limit.is_a?(Integer) && limit >= 1 && limit <= 1000)
+        raise search_error('vector limit must be an integer from 1 to 1000')
+      end
+
+      @vector = { 'column' => column, 'vector' => embedding }
+      @vector['metric'] = metric unless metric == 'cosine'
+      @vector['limit'] = limit unless limit.nil?
+      self
+    end
+
     def execute
+      return execute_vector_search if @vector
+
       HttpTransport.request(
         config: @config, method: 'GET',
         path: FromBuilder.collection_path(@config, @collection),
-        query: to_query
+        query: to_query.merge(@search)
+      )
+    end
+
+    private
+
+    BODY_KEYS = %w[select order limit cursor count or].freeze
+
+    # POST data/<collection>/search: the vector search entry becomes an object, filters go under +filter+, and the
+    # list keys (select, order, limit, cursor, count, or) stay at the top level.
+    def execute_vector_search
+      raise search_error('text_search cannot be combined with vector_search') if @search.key?('textSearch')
+
+      body = { 'vectorSearch' => @vector }
+      filter = {}
+      to_query.each do |key, value|
+        if BODY_KEYS.include?(key)
+          body[key] = key == 'limit' ? @limit_val : value
+        else
+          filter[key] = value
+        end
+      end
+      body['filter'] = filter unless filter.empty?
+      HttpTransport.request(
+        config: @config, method: 'POST',
+        path: "#{FromBuilder.collection_path(@config, @collection)}/search", body: body
       )
     end
+
+    def search_error(message)
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: { collection: @collection })
+    end
+
+    def check_search_column(column)
+      return if column.is_a?(String) && column.match?(SEARCH_COLUMN)
+
+      raise search_error('search column must be a column name: letters, digits and underscores, starting with a letter or underscore')
+    end
   end
 
   class UpdateBuilder < BaseBuilder
@@ -128,6 +232,13 @@ module K9o
       @patch = patch
     end
 
+    # Ask for this update to wait for approval (+?requireApproval=true+). The answer is then a queued change or, when an
+    # +auto_approve+ policy covers the write, the updated row: check it with K9o.queued_write?.
+    def require_approval
+      @require_approval = true
+      self
+    end
+
     def execute
       id_filter = @filters.find { |col, op, _| col == 'id' && op == 'eq' }
       raise KError.new(
@@ -137,11 +248,19 @@ module K9o
       ) unless id_filter
 
       path = "#{FromBuilder.collection_path(@config, @collection)}/#{id_filter[2]}"
-      HttpTransport.request(config: @config, method: 'PATCH', path: path, body: @patch)
+      HttpTransport.request(config: @config, method: 'PATCH', path: path, body: @patch,
+                            query: FromBuilder.approval_query(@require_approval))
     end
   end
 
   class DeleteBuilder < BaseBuilder
+    # Ask for this delete to wait for approval (+?requireApproval=true+). The answer is then a queued change or, when an
+    # +auto_approve+ policy covers the write, the deleted record: check it with K9o.queued_write?.
+    def require_approval
+      @require_approval = true
+      self
+    end
+
     def execute
       id_filter = @filters.find { |col, op, _| col == 'id' && op == 'eq' }
       raise KError.new(
@@ -151,7 +270,8 @@ module K9o
       ) unless id_filter
 
       path = "#{FromBuilder.collection_path(@config, @collection)}/#{id_filter[2]}"
-      HttpTransport.request(config: @config, method: 'DELETE', path: path)
+      HttpTransport.request(config: @config, method: 'DELETE', path: path,
+                            query: FromBuilder.approval_query(@require_approval))
     end
   end
 end

data/lib/k9o/ed25519.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module K9o
+  # Ed25519 signature verification (RFC 8032). Uses the openssl library when the Ruby in use can verify Ed25519, and
+  # an in-process implementation (plain integer arithmetic) otherwise, so the answer never depends on the build of
+  # OpenSSL underneath Ruby.
+  module Ed25519
+    P = (2**255) - 19
+    L = (2**252) + 27_742_317_777_372_353_535_851_937_790_883_648_493
+    D = (-121_665 * 121_666.pow(P - 2, P)) % P
+    SQRT_M1 = 2.pow((P - 1) / 4, P)
+    BASE_Y = (4 * 5.pow(P - 2, P)) % P
+
+    module_function
+
+    # True when +signature+ (64 bytes) is a valid Ed25519 signature of +message+ under +public_key+ (32 bytes).
+    # Malformed input answers false.
+    def verify(public_key, message, signature)
+      public_key = public_key.b
+      message = message.b
+      signature = signature.b
+      return false unless public_key.bytesize == 32 && signature.bytesize == 64
+
+      if native?
+        verify_native(public_key, message, signature)
+      else
+        Pure.verify(public_key, message, signature)
+      end
+    end
+
+    # True when this Ruby's openssl can verify Ed25519 signatures.
+    def native?
+      return @native unless @native.nil?
+
+      @native = begin
+        OpenSSL::PKey.respond_to?(:new_raw_public_key) &&
+          OpenSSL::PKey.new_raw_public_key('ED25519', ("\x00".b * 31) + "\x01".b).respond_to?(:verify)
+      rescue StandardError
+        false
+      end
+    end
+
+    def verify_native(public_key, message, signature)
+      OpenSSL::PKey.new_raw_public_key('ED25519', public_key).verify(nil, signature, message)
+    rescue OpenSSL::PKey::PKeyError, ArgumentError
+      false
+    end
+
+    # RFC 8032 section 5.1 in plain integers (extended coordinates).
+    module Pure
+      P = Ed25519::P
+      L = Ed25519::L
+      D = Ed25519::D
+      IDENTITY = [0, 1, 1, 0].freeze
+
+      module_function
+
+      def verify(public_key, message, signature)
+        a_point = decode_point(public_key)
+        return false if a_point.nil?
+
+        r_bytes = signature.byteslice(0, 32)
+        s = int_le(signature.byteslice(32, 32))
+        return false unless s < L
+        return false if decode_point(r_bytes).nil?
+
+        k = int_le(sha512(r_bytes + public_key + message)) % L
+        # [s]B - [k]A must equal R.
+        check = add(scalar_mult(base, s), scalar_mult(negate(a_point), k))
+        encode_point(check) == r_bytes
+      end
+
+      # The 32-byte public key for a 32-byte seed. Exposed so tests can sign with a fresh key.
+      def public_key(seed)
+        encode_point(scalar_mult(base, expand(seed).first))
+      end
+
+      # A 64-byte signature of +message+ by +seed+. Exposed so tests can sign; callers verify with Ed25519.verify.
+      def sign(seed, message)
+        a, prefix = expand(seed)
+        pub = encode_point(scalar_mult(base, a))
+        r = int_le(sha512(prefix + message)) % L
+        r_bytes = encode_point(scalar_mult(base, r))
+        k = int_le(sha512(r_bytes + pub + message)) % L
+        r_bytes + le32((r + (k * a)) % L)
+      end
+
+      def expand(seed)
+        h = sha512(seed)
+        a = int_le(h.byteslice(0, 32))
+        a &= (1 << 254) - 8
+        a |= 1 << 254
+        [a, h.byteslice(32, 32)]
+      end
+
+      def sha512(data)
+        OpenSSL::Digest::SHA512.digest(data)
+      end
+
+      def int_le(bytes)
+        bytes.unpack('C*').each_with_index.sum { |byte, i| byte << (8 * i) }
+      end
+
+      def le32(int)
+        Array.new(32) { |i| (int >> (8 * i)) & 0xff }.pack('C*')
+      end
+
+      def base
+        x = recover_x(Ed25519::BASE_Y, 0)
+        [x, Ed25519::BASE_Y, 1, (x * Ed25519::BASE_Y) % P]
+      end
+
+      def recover_x(y, sign)
+        return nil if y >= P
+
+        x2 = ((y * y) - 1) * ((D * y * y) + 1).pow(P - 2, P) % P
+        if x2.zero?
+          return sign.zero? ? 0 : nil
+        end
+
+        x = x2.pow((P + 3) / 8, P)
+        x = (x * Ed25519::SQRT_M1) % P unless ((x * x) - x2) % P == 0
+        return nil unless ((x * x) - x2) % P == 0
+
+        x = P - x if (x & 1) != sign
+        x
+      end
+
+      def decode_point(bytes)
+        return nil unless bytes.bytesize == 32
+
+        y = int_le(bytes)
+        sign = y >> 255
+        y &= (1 << 255) - 1
+        x = recover_x(y, sign)
+        return nil if x.nil?
+
+        [x, y, 1, (x * y) % P]
+      end
+
+      def encode_point(point)
+        x, y, z, = point
+        zinv = z.pow(P - 2, P)
+        xa = (x * zinv) % P
+        ya = (y * zinv) % P
+        le32(ya | ((xa & 1) << 255))
+      end
+
+      def add(p1, p2)
+        x1, y1, z1, t1 = p1
+        x2, y2, z2, t2 = p2
+        a = ((y1 - x1) * (y2 - x2)) % P
+        b = ((y1 + x1) * (y2 + x2)) % P
+        c = (2 * t1 * t2 * D) % P
+        d = (2 * z1 * z2) % P
+        e = b - a
+        f = d - c
+        g = d + c
+        h = b + a
+        [(e * f) % P, (g * h) % P, (f * g) % P, (e * h) % P]
+      end
+
+      def negate(point)
+        x, y, z, t = point
+        [(-x) % P, y, z, (-t) % P]
+      end
+
+      def scalar_mult(point, scalar)
+        result = IDENTITY
+        addend = point
+        while scalar.positive?
+          result = add(result, addend) if scalar.odd?
+          addend = add(addend, addend)
+          scalar >>= 1
+        end
+        result
+      end
+    end
+  end
+end

data/lib/k9o/end_users.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module K9o
+  # End users: k9o.end_users.*, the people who sign in to the project's own apps.
+  #
+  #   list(status:, q:, limit:, cursor:)       GET /@<slug>/end-users
+  #   get(id)                                  GET /@<slug>/end-users/<id>
+  #   role_grants.list(end_user_id:)           GET    /@<slug>/end-user-role-grants
+  #   role_grants.grant(end_user_id:, role:)   POST   /@<slug>/end-user-role-grants
+  #   role_grants.revoke(grant_id)             DELETE /@<slug>/end-user-role-grants/<grant_id>
+  #
+  # Listing and reading end users needs the project admin role. Role grants are created and revoked by project
+  # admins; reading them is open to a wider set of project roles.
+  class EndUsers
+    STATUSES = %w[active locked deleted all].freeze
+
+    attr_reader :role_grants
+
+    def initialize(config)
+      @config = config
+      @role_grants = EndUserRoleGrants.new(config)
+    end
+
+    # End users, newest first, one page at a time. +status+ is active, locked, deleted or all (default: active and
+    # locked); +q+ is an email prefix; +limit+ is 1 to 200 (default 50).
+    def list(status: nil, q: nil, limit: nil, cursor: nil)
+      ApprovalChecks.check_limit(limit)
+      query = {}
+      query['status'] = ApprovalChecks.enum!(status, STATUSES, 'status') unless status.nil?
+      query['q'] = q unless q.nil?
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor unless cursor.nil?
+      HttpTransport.request(config: @config, method: 'GET', path: path('end-users'), query: query)
+    end
+
+    # One end user. An unknown id is a 404 K9O_END_USER_NOT_FOUND.
+    def get(id)
+      HttpTransport.request(config: @config, method: 'GET',
+                            path: path("end-users/#{ApprovalChecks.id_segment(id, 'end user')}"))
+    end
+
+    private
+
+    def path(tail)
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'end_users'), tail)
+    end
+  end
+
+  # A role is a free string (1 to 128 characters), not a fixed list.
+  class EndUserRoleGrants
+    def initialize(config)
+      @config = config
+    end
+
+    # The active grants, oldest first. Not paginated. +data+ is the array of grants (the gateway wraps it in
+    # { 'grants' => [...] }). An unknown +end_user_id+ answers an empty list.
+    def list(end_user_id: nil)
+      query = {}
+      query['endUserId'] = end_user_id unless end_user_id.nil?
+      unwrap(HttpTransport.request(config: @config, method: 'GET', path: path, query: query), 'grants')
+    end
+
+    # Give an end user a role; +data+ is the grant. Granting a role the user already holds is a 400
+    # K9O_INVALID_FIELD_VALUE; an unknown end user is a 404 K9O_NOT_FOUND. A revoked role can be granted again.
+    def grant(end_user_id:, role:)
+      body = { 'endUserId' => text!(end_user_id, 'end_user_id', 64), 'role' => text!(role, 'role', 128) }
+      unwrap(HttpTransport.request(config: @config, method: 'POST', path: path, body: body), 'grant')
+    end
+
+    # Revoke a grant (it is kept, marked revoked). +data+ is { 'revoked' => true|false, 'revokedAt' => ... }; an
+    # unknown or already revoked id is not an error, it answers revoked false and revokedAt nil.
+    def revoke(grant_id)
+      HttpTransport.request(config: @config, method: 'DELETE',
+                            path: path("/#{ApprovalChecks.id_segment(grant_id, 'grant')}"))
+    end
+
+    private
+
+    def unwrap(envelope, key)
+      Envelope.new(data: envelope.data.is_a?(Hash) ? envelope.data[key] : envelope.data, meta: envelope.meta)
+    end
+
+    def text!(value, what, max)
+      return value if value.is_a?(String) && !value.empty? && value.length <= max
+
+      raise ApprovalChecks.invalid("#{what} must be a string of 1 to #{max} characters")
+    end
+
+    def path(tail = '')
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'end_users'), "end-user-role-grants#{tail}")
+    end
+  end
+end

data/lib/k9o/envelope.rb

@@ -20,9 +20,10 @@ module K9o
 
   # Meta accessor sugar.
   class Meta
-    attr_reader :cursor, :subscription, :idempotency, :warnings, :cost, :timing, :context
+    attr_reader :cursor, :subscription, :idempotency, :warnings, :cost, :timing, :context, :approval
 
-    def initialize(cursor: nil, subscription: nil, idempotency: nil, warnings: [], cost: {}, timing: nil, context: nil)
+    def initialize(cursor: nil, subscription: nil, idempotency: nil, warnings: [], cost: {}, timing: nil, context: nil,
+                   approval: nil)
       @cursor = cursor
       @subscription = subscription
       @idempotency = idempotency
@@ -30,6 +31,7 @@ module K9o
       @cost = cost
       @timing = timing
       @context = context
+      @approval = approval
     end
 
     def self.from_wire(wire)
@@ -38,11 +40,12 @@ module K9o
       idem = wire['idempotency'] ? MetaIdempotency.new(replayed: !!wire['idempotency']['replayed']) : nil
       warnings = (wire['warnings'] || []).map { |w| MetaWarning.new(code: w['code'] || '', message: w['message'] || '') }
       timing = wire['timing'] ? MetaTiming.new(total_ms: wire['timing']['totalMs'].to_i) : nil
-      context = wire['context'] && wire['context']['requestId'] ? MetaContext.new(request_id: wire['context']['requestId']) : nil
+      context = wire['context'] && wire['context']['requestId'] ? MetaContext.new(request_id: wire['context']['requestId'], project_id: wire['context']['projectId']) : nil
       Meta.new(
         cursor: cursor, subscription: sub, idempotency: idem,
         warnings: warnings, cost: wire['cost'] || {},
-        timing: timing, context: context
+        timing: timing, context: context,
+        approval: wire['approval'].is_a?(Hash) ? wire['approval'] : nil
       )
     end
   end
@@ -60,5 +63,17 @@ module K9o
   MetaIdempotency = Struct.new(:replayed, keyword_init: true)
   MetaWarning = Struct.new(:code, :message, keyword_init: true)
   MetaTiming = Struct.new(:total_ms, keyword_init: true)
-  MetaContext = Struct.new(:request_id, keyword_init: true)
+  MetaContext = Struct.new(:request_id, :project_id, keyword_init: true)
+end
+
+module K9o
+  # A binary download answer: the bytes exactly as sent and the content type the gateway named (or nil).
+  class Download
+    attr_reader :body, :content_type
+
+    def initialize(body:, content_type: nil)
+      @body = body
+      @content_type = content_type
+    end
+  end
 end