k9o 1.2.0-aarch64-linux → 1.5.2-aarch64-linux

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

data/lib/k9o/schema.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module K9o
+  # Schema: k9o.schema.*
+  #
+  #   collections.list(limit:, cursor:)    GET /@<slug>/schema/collections
+  #
+  # The list is cursor-paginated and ordered by collection name: pass +meta.cursor.next+ of one page as +cursor+ of
+  # the next, until it is nil.
+  class Schema
+    attr_reader :collections
+
+    def initialize(config)
+      @collections = SchemaCollections.new(config)
+    end
+  end
+
+  class SchemaCollections
+    def initialize(config)
+      @config = config
+    end
+
+    # The project's collections by name, one page at a time. +limit+ is 1 to 200 (default 50).
+    def list(limit: nil, cursor: nil)
+      route = UrlGrammar.project_path(Studio.require_project_slug(@config, 'schema'), 'schema/collections')
+      ApprovalChecks.check_limit(limit)
+      raise ApprovalChecks.invalid('cursor must be a string', cursor: cursor) unless cursor.nil? || cursor.is_a?(String)
+
+      query = {}
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor unless cursor.nil?
+      HttpTransport.request(config: @config, method: 'GET', path: route, query: query)
+    end
+  end
+end

data/lib/k9o/streams.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module K9o
+  # User data streams namespace: k9o.streams.*.
+  #
+  # Routes under /@<slug>/data-streams/user. Publish needs project admin; subscribe and replay need admin or
+  # auditor. While the stream data plane is unavailable the gateway answers K9O_STREAM_UNAVAILABLE (503); a bad
+  # subject answers K9O_STREAM_INVALID. Both raise K9o::KError.
+  class Streams
+    @reconnect_delay = 0.25
+
+    class << self
+      # Seconds to wait before reconnecting after the server closes a subscribe connection.
+      attr_accessor :reconnect_delay
+    end
+
+    def initialize(config)
+      @config = config
+    end
+
+    # POST /@<slug>/data-streams/user — +max_bytes+ is the storage ceiling; the slug is derived from +display_name+.
+    def create(display_name, max_bytes, retention_seconds: nil)
+      body = { 'displayName' => display_name, 'maxBytes' => max_bytes }
+      body['retentionSeconds'] = retention_seconds unless retention_seconds.nil?
+      call('POST', path, body)
+    end
+
+    # GET /@<slug>/data-streams/user — the project's active user streams.
+    def list
+      call('GET', path)
+    end
+
+    # GET /@<slug>/data-streams/user/<slug>
+    def get(slug)
+      call('GET', path(slug))
+    end
+
+    # DELETE /@<slug>/data-streams/user/<slug> — retire the stream.
+    def delete(slug)
+      call('DELETE', path(slug))
+    end
+
+    # POST .../<slug>/publish — +data+ is any JSON value; +subject+ is an optional dot-separated routing suffix.
+    def publish(slug, data, subject: nil)
+      body = { 'data' => data }
+      body['subject'] = subject unless subject.nil?
+      call('POST', path(slug, 'publish'), body)
+    end
+
+    # POST .../<slug>/replay — a bounded range of past events: data['events'], data['nextCursor'], data['hasMore'].
+    def replay(slug, from_sequence: nil, until_sequence: nil, limit: nil)
+      body = {}
+      body['fromSequence'] = from_sequence unless from_sequence.nil?
+      body['untilSequence'] = until_sequence unless until_sequence.nil?
+      body['limit'] = limit unless limit.nil?
+      call('POST', path(slug, 'replay'), body)
+    end
+
+    # GET .../<slug>/subscribe — an Enumerator tailing live events { 'sequence', 'subject', 'data', 'publishedAt' }.
+    # The gateway bounds each connection and closes it; the enumerator reconnects from the last sequence it yielded.
+    # Stop by leaving the +each+ block (break) or by taking a finite number (+first(n)+).
+    def subscribe(slug, from_sequence: nil)
+      route = path(slug, 'subscribe')
+      Enumerator.new do |yielder|
+        cursor = from_sequence
+        loop do
+          query = cursor.nil? ? nil : { 'fromSequence' => cursor.to_s }
+          HttpTransport.stream_sse(config: @config, method: 'GET', path: route, query: query).each do |event|
+            next unless event.is_a?(Hash) && event.key?('sequence')
+
+            cursor = event['sequence']
+            yielder << event
+          end
+          delay = self.class.reconnect_delay
+          sleep(delay) if delay.positive?
+        end
+      end
+    end
+
+    private
+
+    def call(method, route, body = nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body)
+    end
+
+    def path(stream_slug = nil, suffix = nil)
+      project = Studio.require_project_slug(@config, 'streams')
+      sub = +'data-streams/user'
+      sub << "/#{::URI.encode_www_form_component(stream_slug)}" if stream_slug
+      sub << "/#{suffix}" if suffix
+      UrlGrammar.project_path(project, sub)
+    end
+  end
+end

data/lib/k9o/studio.rb

@@ -25,7 +25,7 @@ module K9o
       slug
     end
 
-    # k9o.studio.workflows.*.
+    # k9o.studio.workflows.*
     class Workflows
       attr_reader :runs
 
@@ -34,17 +34,19 @@ module K9o
         @runs = Runs.new(config)
       end
 
-      def list(status: nil, trigger_type: nil, limit: nil, cursor: nil)
+      # GET /@<slug>/workflows — the route filters by +status+ and pages with +limit+ / +cursor+.
+      def list(status: nil, limit: nil, cursor: nil)
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         q = {}
         q['status'] = status if status
-        q['triggerType'] = trigger_type if trigger_type
         q['limit'] = limit if limit
         q['cursor'] = cursor if cursor
         HttpTransport.request(config: @config, method: 'GET',
                               path: UrlGrammar.project_path(slug, 'workflows'), query: q)
       end
 
+      # POST /@<slug>/workflows. +workflow+ is the gateway's body: 'name', 'triggerType', 'triggerConfig',
+      # 'actions' (each { 'index', 'action_type', 'config', ... }), optional 'description', 'status', 'rbacBinding'.
       def create(workflow)
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         HttpTransport.request(config: @config, method: 'POST',
@@ -69,12 +71,12 @@ module K9o
                               path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}"))
       end
 
-      # Manual-trigger a run (trigger_type=manual only).
+      # Manual-trigger a run (manual workflows only): POST /@<slug>/workflows/<id>/runs { triggerContext }.
       def trigger(workflow_id, trigger_context = {})
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         HttpTransport.request(config: @config, method: 'POST',
                               path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}/runs"),
-                              body: trigger_context)
+                              body: { 'triggerContext' => trigger_context })
       end
 
       private
@@ -83,15 +85,18 @@ module K9o
         ::URI.encode_www_form_component(s)
       end
 
-      # k9o.studio.workflows.runs.*.
+      # k9o.studio.workflows.runs.*
       class Runs
         def initialize(config)
           @config = config
         end
 
-        def list(workflow_id, status: nil)
+        # GET /@<slug>/workflows/<id>/runs — pages with +limit+ / +cursor+ (the route has no status filter).
+        def list(workflow_id, limit: nil, cursor: nil)
           slug = Studio.require_project_slug(@config, 'studio.workflows')
-          q = status ? { 'status' => status } : nil
+          q = {}
+          q['limit'] = limit if limit
+          q['cursor'] = cursor if cursor
           HttpTransport.request(config: @config, method: 'GET',
                                 path: UrlGrammar.project_path(slug, "workflows/#{enc(workflow_id)}/runs"), query: q)
         end
@@ -116,15 +121,20 @@ module K9o
       end
     end
 
-    # k9o.studio.dashboards.*.
+    # k9o.studio.dashboards.* — widget fields on the wire are snake_case ('widget_type', 'data_source', 'config').
     class Dashboards
       def initialize(config)
         @config = config
       end
 
-      def list(status: nil)
+      # GET /@<slug>/dashboards — filters: +status+, +pinned_only+; pages with +limit+ / +cursor+.
+      def list(status: nil, pinned_only: nil, limit: nil, cursor: nil)
         slug = Studio.require_project_slug(@config, 'studio.dashboards')
-        q = status ? { 'status' => status } : nil
+        q = {}
+        q['status'] = status if status
+        q['pinnedOnly'] = pinned_only.to_s unless pinned_only.nil?
+        q['limit'] = limit if limit
+        q['cursor'] = cursor if cursor
         HttpTransport.request(config: @config, method: 'GET',
                               path: UrlGrammar.project_path(slug, 'dashboards'), query: q)
       end

data/lib/k9o/url_grammar.rb

@@ -7,11 +7,18 @@ module K9o
   module UrlGrammar
     SLUG_RE = /\A[a-z][a-z0-9-]{1,62}\z/
 
-    # Bare platform apex hosts org-subdomain derivation applies to —
-    # production and staging share the <org_slug>.<apex> wire-routing
-    # scheme (confirmed live). A third apex needs the same confirmation
-    # before joining this set.
-    ORG_DERIVABLE_APEXES = %w[api.k9o.io api-staging.k9o.io].freeze
+    # The convenience default when the caller passes no base_url. A default value only: never used to parse a host.
+    DEFAULT_BASE_URL = 'https://api.k9o.io'
+
+    # `api` or `api-staging`, optionally followed by `-<rgn>`: the label that marks a gateway host.
+    API_LABEL = /\A(api|api-staging)(?:-([a-z]{2}\d{2}))?\z/.freeze
+
+    # The structure of a gateway API host, read from the host itself.
+    #   org_slug: first label of an org host (+acme+ in +acme.api.corp.internal+); nil for a platform host.
+    #   family:   +api+ or +api-staging+.
+    #   region:   4-character region code when the host is regional (+api-de01+), else nil.
+    #   apex:     everything after the gateway label; never matched against a list.
+    ApiHost = Struct.new(:org_slug, :family, :region, :apex)
 
     module_function
 
@@ -65,24 +72,43 @@ module K9o
       "#{uri.scheme}://#{host_port}"
     end
 
-    # Resolve the effective base_url. base_url is
-    # OPTIONAL — it defaults to the platform apex https://api.k9o.io. When the
-    # (validated) host is a bare apex in ORG_DERIVABLE_APEXES and org_slug is
-    # supplied, the SDK composes the canonical org-subdomain wire root
-    # https://<org_slug>.<apex>. An explicit <org_slug> subdomain,
-    # a self-hosted / Sovereign host, or a dev host (anything not in that
-    # set) passes through unchanged — org_slug is intentionally NOT composed
-    # onto a non-apex host.
-    #
-    # Fixed 2026-08-30 (SDK-2): this used to silently ignore org_slug for
-    # api-staging.k9o.io too, not just genuine self-hosted/custom hosts,
-    # since only the literal production apex string was checked.
+    # Read the org slug and region out of a gateway host without knowing its apex. The gateway label is +api+ or
+    # +api-staging+, optionally followed by +-<rgn>+; the label before it is the org slug and whatever follows it is
+    # the apex. Returns nil for any other shape (localhost, an IP, a single-label host, a host with no gateway
+    # label), which callers use exactly as given.
+    def parse_api_host(host)
+      labels = host.to_s.downcase.split('.', -1)
+      return nil if labels.empty? || labels.any?(&:empty?)
+
+      build = lambda do |gateway_label, org_slug, rest|
+        m = API_LABEL.match(gateway_label)
+        next nil if m.nil? || rest.empty?
+
+        ApiHost.new(org_slug, m[1], m[2], rest.join('.'))
+      end
+      # Org host first: <org>.<api[-rgn]>.<apex>.
+      if labels.length >= 3 && labels[0].match?(SLUG_RE) && !labels[0].end_with?('-') && API_LABEL.match?(labels[1])
+        return build.call(labels[1], labels[0], labels[2..-1])
+      end
+      # Platform host: api.<apex>.
+      return build.call(labels[0], nil, labels[1..-1]) if labels.length >= 2 && API_LABEL.match?(labels[0])
+
+      nil
+    end
+
+    # Resolve the effective base_url. base_url is OPTIONAL: omitted, it defaults to DEFAULT_BASE_URL (the public
+    # cloud, a convenience only). When the (validated) host is a platform host (+api.<apex>+ or +api-staging.<apex>+,
+    # any apex) and org_slug is supplied, the canonical org host +<org_slug>.<host>+ is composed. Any other host (an
+    # org host already, an internal or air-gapped host, localhost) passes through unchanged; org_slug is then only
+    # sent as a header.
     def resolve_base_url(base_url, org_slug = nil)
-      validated = validate_base_url(base_url.nil? ? 'https://api.k9o.io' : base_url)
+      validated = validate_base_url(base_url.nil? ? DEFAULT_BASE_URL : base_url)
       uri = URI.parse(validated)
-      if ORG_DERIVABLE_APEXES.include?(uri.host) && org_slug
+      host = parse_api_host(uri.host)
+      if !host.nil? && host.org_slug.nil? && host.region.nil? && org_slug
         validate_slug(org_slug, 'org')
-        return "#{uri.scheme}://#{org_slug}.#{uri.host}"
+        host_port = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        return "#{uri.scheme}://#{org_slug}.#{host_port}"
       end
       validated
     end