k9o 1.2.0 → 1.4.0

data/lib/k9o/query.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module K9o
+  # `client.query(sql, params)` and `client.search(collection, column:, q:)`.
+  #
+  # Wire (project-plane):
+  #   POST /@<slug>/query   body { sql:, params? }   -> { data: [row, ...], meta }
+  #   GET  /@<slug>/data/<collection>?textSearch=<column>:<q>...   (the select builder's +text_search+)
+  #
+  # +params+ is an Array (positional, bound to $1, $2, ...; the SQL is sent as written) or a Hash of named values
+  # (+:name+ placeholders are rewritten to $n here and the values become the positional list). Values are bound by
+  # the database, never interpolated into the SQL text.
+  module Query
+    IDENT_START = /[A-Za-z_]/.freeze
+    IDENT_CHAR = /[A-Za-z0-9_]/.freeze
+    DOLLAR_TAG = /\A\$([A-Za-z_][A-Za-z0-9_]*)?\$/.freeze
+
+    module_function
+
+    def invalid(message, context = {})
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: context)
+    end
+
+    def check_value(value, where)
+      return value if value.nil? || value == true || value == false || value.is_a?(String)
+      return value if value.is_a?(Integer)
+      return value if value.is_a?(Float) && value.finite?
+
+      raise invalid("#{where} must be a string, number, boolean or nil; serialise anything else (for example as JSON text) first")
+    end
+
+    def lookup(named, name)
+      return [true, named[name]] if named.key?(name)
+      return [true, named[name.to_sym]] if named.key?(name.to_sym)
+
+      [false, nil]
+    end
+
+    # Rewrite +:name+ placeholders to $n. Skips quoted text, comments, dollar-quoted strings and +::+ casts.
+    # Returns [sql, params].
+    def translate_named_params(sql, named)
+      order = []
+      out = +''
+      i = 0
+      n = sql.length
+      while i < n
+        c = sql[i]
+        nxt = i + 1 < n ? sql[i + 1] : ''
+        if c == "'" || ((c == 'E' || c == 'e') && nxt == "'" && !(i > 0 && sql[i - 1] =~ IDENT_CHAR))
+          escapes = c != "'"
+          j = escapes ? i + 2 : i + 1
+          while j < n
+            if escapes && sql[j] == '\\'
+              j += 2
+              next
+            end
+            if sql[j] == "'"
+              if sql[j + 1] == "'"
+                j += 2
+                next
+              end
+              break
+            end
+            j += 1
+          end
+          out << sql[i...[j + 1, n].min]
+          i = j + 1
+        elsif c == '"'
+          j = i + 1
+          while j < n
+            if sql[j] == '"'
+              if sql[j + 1] == '"'
+                j += 2
+                next
+              end
+              break
+            end
+            j += 1
+          end
+          out << sql[i...[j + 1, n].min]
+          i = j + 1
+        elsif c == '-' && nxt == '-'
+          j = sql.index("\n", i) || n
+          out << sql[i...j]
+          i = j
+        elsif c == '/' && nxt == '*'
+          depth = 1
+          j = i + 2
+          while j < n && depth > 0
+            if sql[j, 2] == '/*'
+              depth += 1
+              j += 2
+            elsif sql[j, 2] == '*/'
+              depth -= 1
+              j += 2
+            else
+              j += 1
+            end
+          end
+          out << sql[i...j]
+          i = j
+        elsif c == '$'
+          m = DOLLAR_TAG.match(sql[i..-1])
+          if m
+            close = sql.index(m[0], i + m[0].length)
+            stop = close.nil? ? n : close + m[0].length
+            out << sql[i...stop]
+            i = stop
+          else
+            out << c
+            i += 1
+          end
+        elsif c == ':' && nxt == ':'
+          out << '::'
+          i += 2
+        elsif c == ':' && nxt != '' && nxt =~ IDENT_START && !(i > 0 && sql[i - 1] =~ IDENT_CHAR)
+          j = i + 2
+          j += 1 while j < n && sql[j] =~ IDENT_CHAR
+          name = sql[(i + 1)...j]
+          unless order.include?(name)
+            found, = lookup(named, name)
+            raise invalid("no value for :#{name}", name: name) unless found
+
+            order << name
+          end
+          out << "$#{order.index(name) + 1}"
+          i = j
+        else
+          out << c
+          i += 1
+        end
+      end
+      values = order.map { |name| check_value(lookup(named, name)[1], "the value for :#{name}") }
+      [out, values]
+    end
+
+    # Builds [path, body] for POST /@<slug>/query.
+    def prepare(config, sql, params)
+      slug = Studio.require_project_slug(config, 'query')
+      text = sql
+      values = []
+      if params.is_a?(Hash)
+        text, values = translate_named_params(sql, params)
+      elsif !params.nil?
+        values = params.each_with_index.map { |v, i| check_value(v, "params[#{i}]") }
+      end
+      body = { 'sql' => text }
+      body['params'] = values unless values.empty?
+      [UrlGrammar.project_path(slug, 'query'), body]
+    end
+  end
+
+  # Client-root methods mixed into K9oClient.
+  module QueryMethods
+    # POST /@<slug>/query — run one read-only SQL statement; +data+ is the array of rows.
+    # An Array binds positionally to $1, $2, ...; a Hash binds +:name+ placeholders.
+    def query(sql, params = nil)
+      path, body = Query.prepare(@config, sql, params)
+      HttpTransport.request(config: @config, method: 'POST', path: path, body: body)
+    end
+
+    # Full-text search over one text column of a collection, best matches first. Sugar over
+    # +from(collection).select.text_search(column, q, ...)+; +limit+ and +cursor+ page the result.
+    def search(collection, column:, q:, language: nil, type: nil, limit: nil, cursor: nil)
+      opts = {}
+      opts[:language] = language unless language.nil?
+      opts[:type] = type unless type.nil?
+      builder = from(collection).select.text_search(column, q, **opts)
+      builder.limit(limit) unless limit.nil?
+      builder.cursor(cursor) unless cursor.nil?
+      builder.execute
+    end
+  end
+end

data/lib/k9o/realtime.rb

@@ -1,54 +1,32 @@
 # frozen_string_literal: true
 
 module K9o
-  # Realtime Subscriptions namespace (ALL-LIVE primitive).
+  # Realtime Subscriptions namespace.
   #
-  # Ruby idiom: #subscribe returns an Enumerator iterated via
-  # `.each`. Per + the SDK-abstracted-primitive discipline the
-  # SDK picks the transport; SPLIT (polling) is the internal fallback. The
-  # Net::HTTP-based Ruby SDK uses SSE primary (no stdlib WebSocket);
-  # #subscribe_poll exposes the poll fallback. #replay is one-shot catch-up.
+  # 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`.
   class Realtime
     def initialize(config)
       @config = config
     end
 
-    # Subscribe via SSE transport (primary); returns an
-    # Enumerator yielding event hashes.
+    # 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)
       slug = Studio.require_project_slug(@config, 'realtime')
       q = { 'topic' => topic }
       q['filter'] = JSON.dump(filter) if filter
-      HttpTransport.stream_sse(config: @config, method: 'GET',
-                               path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
-    end
-
-    # One-shot historical replay (capped 10k server-side).
-    def replay(topic, from_sequence:, filter: nil, until_sequence: nil, limit: nil)
-      slug = Studio.require_project_slug(@config, 'realtime')
-      unless from_sequence.is_a?(Integer) && from_sequence >= 0
-        raise KError.new(
-          code: 'K9O_INVALID_FILTER',
-          message: 'replay from_sequence must be a non-negative integer',
-          context: { fromSequence: from_sequence },
-          recommendation: 'Pass the highest sequence number you have already observed (or 0 to replay from the start).'
-        )
+      frames = HttpTransport.stream_sse(config: @config, method: 'GET',
+                                        path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
+      Enumerator.new do |yielder|
+        frames.each do |event|
+          yielder << event if event.is_a?(Hash) && event['eventType'].is_a?(String)
+        end
       end
-      body = { 'topic' => topic, 'fromSequence' => from_sequence }
-      body['filter'] = filter if filter
-      body['untilSequence'] = until_sequence if until_sequence
-      body['limit'] = limit if limit
-      HttpTransport.request(config: @config, method: 'POST',
-                            path: UrlGrammar.project_path(slug, 'realtime/replay'), body: body)
-    end
-
-    # Poll-transport fallback (SDK-internal SPLIT). Single batch
-    # via replay endpoint; caller loops tracking highest observed sequence.
-    def subscribe_poll(topic, from_sequence:, filter: nil)
-      replay(topic, from_sequence: from_sequence, filter: filter)
     end
 
-    # Typed builders for the 6 closed topic families.
     module Topic
       module_function
 

data/lib/k9o/region.rb

@@ -6,30 +6,32 @@ require 'uri'
 module K9o
   # Regional host resolution.
   #
-  # The region-free org host `<org>.api[-staging].k9o.io` redirects GET/HEAD
-  # only and REFUSES a request carrying a body / Authorization / cookie, so
-  # credentials must go to `<org>.api[-staging]-<rgn>.k9o.io`. The SDK learns
-  # the region with ONE unauthenticated `HEAD https://<org>.api[-staging].k9o.io/`
-  # (Net::HTTP never follows redirects, so the 308 is read, not followed),
+  # A region-free org host `<org>.api.<rest>` (or `<org>.api-staging.<rest>`)
+  # redirects GET/HEAD only and REFUSES a request carrying a body /
+  # Authorization / cookie, so credentials must go to `<org>.api-<rgn>.<rest>`.
+  # The SDK learns the region with ONE unauthenticated HEAD to the configured
+  # host (Net::HTTP never follows redirects, so the 308 is read, not followed),
   # takes the 308 `Location`, and caches the regional origin per client config.
   #
-  # - Only a region-free org host is ever probed; any other base URL is used
-  #   exactly as given.
+  # Nothing here knows an apex: the host comes from the configured base URL and
+  # `<rest>` is whatever follows the gateway label, so public-cloud,
+  # internal-apex, air-gapped and localhost deployments all work.
+  #
+  # - Only a region-free org host (see UrlGrammar.parse_api_host) is ever
+  #   probed; any other base URL is used exactly as given.
   # - The probe carries no Authorization, cookie or default header.
   # - The Location is trusted only if https, no userinfo, no port, and host is
-  #   exactly `<same org>.<same apex family>-<rgn>.k9o.io` (rgn = [a-z]{2}\d{2}).
+  #   exactly the same org and the same remainder with a region code
+  #   ([a-z]{2}\d{2}) appended to the gateway label.
   # - Any other status or failure keeps the configured base URL. A definite
   #   answer is cached; a network failure of the probe is not.
   module Region
-    REGION_FREE_ORG_HOST = /\A([a-z][a-z0-9-]{1,62})\.(api|api-staging)\.k9o\.io\z/.freeze
-    REGION_CODE = /\A[a-z]{2}\d{2}\z/.freeze
-
     module_function
 
     # The regional origin `location` may name for `host`, or nil. Pure.
     def origin_from_location(host, location, base)
-      m = REGION_FREE_ORG_HOST.match(host)
-      return nil if m.nil?
+      from = UrlGrammar.parse_api_host(host)
+      return nil if from.nil? || from.org_slug.nil? || !from.region.nil?
 
       begin
         u = URI.join(base.sub(%r{/+\z}, '') + '/', location)
@@ -40,11 +42,10 @@ module K9o
       return nil unless u.userinfo.nil? && u.user.nil? && u.password.nil?
       return nil unless u.port == u.default_port
 
-      org = Regexp.escape(m[1])
-      apex = Regexp.escape(m[2])
       h = u.host.to_s.downcase
-      r = /\A#{org}\.#{apex}-([a-z0-9]+)\.k9o\.io\z/.match(h)
-      return nil if r.nil? || !REGION_CODE.match?(r[1])
+      to = UrlGrammar.parse_api_host(h)
+      return nil if to.nil? || to.region.nil?
+      return nil unless to.org_slug == from.org_slug && to.family == from.family && to.apex == from.apex
 
       "https://#{h}"
     end
@@ -70,7 +71,8 @@ module K9o
       rescue URI::Error
         return [configured, true]
       end
-      return [configured, true] unless REGION_FREE_ORG_HOST.match?(host)
+      parsed_host = UrlGrammar.parse_api_host(host)
+      return [configured, true] if parsed_host.nil? || parsed_host.org_slug.nil? || !parsed_host.region.nil?
 
       begin
         probe_uri = URI.parse("#{configured.sub(%r{/+\z}, '')}/")

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