axhub-sdk 0.4.0 → 0.6.0

data/lib/axhub_sdk/data/errors.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module AxHub
-  module Data
-    # Typed data-layer errors. These subclass the existing single AxHub::Error so
-    # the (category, code) contract that the conformance vectors + error tests
-    # match on keeps working, while callers can still rescue the specific failure
-    # (mirrors node/python LegacyCursorError / InvalidCursorError / ValidationError
-    # / TableNotFoundError / IntrospectFailedError / ScanLimitExceededError).
-    class ValidationError < AxHub::Error
-      def initialize(message, code = 'validation', status: 0, retryable: false, request_id: nil)
-        super(category: 'validation', code: code, message: message, status: status, retryable: retryable, request_id: request_id)
-      end
-    end
-
-    # Raised when an after/before keyset or v1:/v2: cursor token is supplied; the
-    # live AX Hub data API is offset-only (mirrors node LegacyCursorError).
-    class LegacyCursorError < AxHub::Error
-      def initialize(message, request_id: nil)
-        super(category: 'validation', code: 'legacy_cursor', message: message, status: 0, retryable: false, request_id: request_id)
-      end
-    end
-
-    class InvalidCursorError < AxHub::Error
-      def initialize(message, request_id: nil)
-        super(category: 'validation', code: 'invalid_cursor', message: message, status: 0, retryable: false, request_id: request_id)
-      end
-    end
-
-    class TableNotFoundError < AxHub::Error
-      def initialize(message, request_id: nil)
-        super(category: 'not_found', code: 'table_not_found', message: message, status: 404, retryable: false, request_id: request_id)
-      end
-    end
-
-    class IntrospectFailedError < AxHub::Error
-      def initialize(message, status: 0, retryable: false, request_id: nil)
-        super(category: 'internal', code: 'introspect_failed', message: message, status: status, retryable: retryable, request_id: request_id)
-      end
-    end
-
-    class ScanLimitExceededError < AxHub::Error
-      def initialize(message, request_id: nil)
-        super(category: 'internal', code: 'scan_limit_exceeded', message: message, status: 0, retryable: false, request_id: request_id)
-      end
-    end
-    # The backend 400s an unfiltered list/count on NON-owner-scoped tables
-    # ("최소 1개의 WHERE 필터가 필요해요") but ACCEPTS it on owner-scoped tables
-    # (rows auto-scope to the caller) — both confirmed live 2026-06. A client
-    # pre-check cannot tell them apart (0.3.0 regression), so the request goes
-    # through and only the backend 400 is normalized.
-    def self.map_where_required(op)
-      yield
-    rescue StandardError => e
-      code = e.respond_to?(:code) ? e.code : nil
-      status = e.respond_to?(:status) ? e.status : nil
-      if code.to_s == 'required' && status.to_i == 400
-        raise ValidationError.new(
-          "AxHub data #{op} requires at least one WHERE filter on this table " \
-          '(the backend rejects unfiltered scans on non-owner-scoped tables). Pass `where:`.',
-          'where_required'
-        )
-      end
-      raise
-    end
-
-  end
-end

data/lib/axhub_sdk/data/pagination.rb

@@ -1,100 +0,0 @@
-# frozen_string_literal: true
-
-module AxHub
-  module Data
-    # Offset pagination helpers (subset of node core pagination that the data
-    # ergonomic layer depends on).
-    #
-    # Ported: serialize_order_by / normalize_order_by, is_v2_cursor,
-    # MAX_CURSOR_TOKEN_LENGTH, list_all, and the PaginatedList / ListAllItem
-    # result shapes. Keyset encode/decode is intentionally NOT ported: the live
-    # AX Hub data API is offset-only, so the data layer only needs the order-by
-    # normalizer and the cursor-shape guards used to reject legacy keyset tokens.
-    MAX_CURSOR_TOKEN_LENGTH = 4096
-
-    PaginatedList = Struct.new(
-      :items, :next_cursor, :first_cursor, :has_next, :has_prev, :total, :total_is_exact,
-      keyword_init: true
-    )
-
-    # Either an item (type == :item) or a drift marker (type == :drift) when the
-    # backend total grows mid-scan.
-    ListAllItem = Struct.new(:type, :value, :added_since, keyword_init: true) do
-      def initialize(type:, value: nil, added_since: 0)
-        super(type: type, value: value, added_since: added_since)
-      end
-    end
-
-    module_function
-
-    # order_by = String | Array<{ field: String, dir?: "asc"|"desc" }>
-    def normalize_order_by(order_by)
-      if order_by.is_a?(String)
-        fields = []
-        order_by.split(',').each do |part|
-          trimmed = part.strip
-          f = if trimmed.start_with?('-')
-                { 'field' => trimmed[1..], 'dir' => 'desc' }
-              elsif trimmed.start_with?('+')
-                { 'field' => trimmed[1..], 'dir' => 'asc' }
-              else
-                { 'field' => trimmed, 'dir' => 'asc' }
-              end
-          fields << f unless f['field'].nil? || f['field'].empty?
-        end
-      elsif order_by && !order_by.empty?
-        fields = order_by.map do |p|
-          h = p.transform_keys(&:to_s)
-          { 'field' => h['field'], 'dir' => h.fetch('dir', 'asc') }
-        end
-      else
-        fields = []
-      end
-      if !fields.empty? && fields.none? { |f| f['field'] == 'id' }
-        fields << { 'field' => 'id', 'dir' => 'asc' }
-      end
-      fields
-    end
-
-    def serialize_order_by(order_by)
-      normalized = normalize_order_by(order_by)
-      return (order_by.is_a?(String) ? order_by : nil) if normalized.empty?
-
-      normalized.map { |f| "#{f['dir'] == 'desc' ? '-' : ''}#{f['field']}" }.join(',')
-    end
-
-    def is_v2_cursor(token)
-      token.is_a?(String) && token.start_with?('v2:')
-    end
-
-    # Drive a paginated fetcher to exhaustion, yielding each item and a drift
-    # marker when the backend total grows mid-iteration (mirrors node listAll).
-    # Returns an Enumerator when no block is given (idiomatic Ruby).
-    def list_all(fetcher, opts = {})
-      return enum_for(:list_all, fetcher, opts) unless block_given?
-
-      cursor = opts[:cursor]
-      initial_total = nil
-      last_total = nil
-      loop do
-        page = fetcher.call(page_size: opts[:page_size], cursor: cursor)
-        unless page.total.nil?
-          if initial_total.nil?
-            initial_total = page.total
-            last_total = page.total
-          else
-            base = last_total.nil? ? initial_total : last_total
-            if page.total > base
-              yield ListAllItem.new(type: :drift, added_since: page.total - base)
-              last_total = page.total
-            end
-          end
-        end
-        page.items.each { |item| yield ListAllItem.new(type: :item, value: item) }
-        return if page.next_cursor.nil?
-
-        cursor = page.next_cursor
-      end
-    end
-  end
-end

data/lib/axhub_sdk/data/projection.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'errors'
-
-module AxHub
-  module Data
-    # Column projection: `select` serialization, validation, and client-side row
-    # narrowing (mirrors node/python projection).
-    #
-    # serialize_select joins columns with commas into the `_select` query param.
-    # validate_select_columns rejects an empty select and, when a schema is known,
-    # unknown columns. project_row/project_rows narrow returned rows to the
-    # selected keys client-side. Rows are string-keyed (camelize-off transport).
-    module_function
-
-    def serialize_select(select)
-      return nil if select.nil?
-
-      select.join(',')
-    end
-
-    def validate_select_columns(schema, select)
-      return if select.nil?
-
-      if select.length.zero?
-        raise ValidationError.new('select must include at least one column; omit select to fetch full rows', 'select_empty')
-      end
-      return if schema.nil?
-
-      allowed = schema.columns.keys
-      invalid = select.reject { |c| allowed.include?(c) }
-      return if invalid.empty?
-
-      plural = invalid.length == 1 ? '' : 's'
-      raise ValidationError.new("select contains unknown column#{plural}: #{invalid.join(', ')}", 'select_unknown_column')
-    end
-
-    def project_row(row, select)
-      return row.dup if select.nil?
-
-      select.each_with_object({}) { |k, acc| acc[k] = row[k] if row.key?(k) }
-    end
-
-    def project_rows(rows, select)
-      return rows.map(&:dup) if select.nil?
-
-      rows.map { |r| project_row(r, select) }
-    end
-  end
-end

data/lib/axhub_sdk/data/schema_cache.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'dsl/schema'
-
-module AxHub
-  module Data
-    # Per-client schema cache for runtime data.discover (mirrors node/python
-    # schema-cache).
-    #
-    # Uses an insertion-ordered Ruby Hash for deterministic LRU eviction
-    # (delete+reinsert = move-to-end on read/write, `shift` = evict oldest) and a
-    # negative-TTL stale-while-error window: a transient 5xx during refresh keeps
-    # the previous entry alive briefly instead of evicting it. The node version
-    # de-dupes concurrent in-flight loads; the sync Ruby port omits the in-flight
-    # map (no concurrency within a single synchronous call).
-    DEFAULT_SCHEMA_CACHE_TTL_MS = 5 * 60_000
-    DEFAULT_SCHEMA_CACHE_MAX_ENTRIES = 1000
-    DEFAULT_SCHEMA_CACHE_NEGATIVE_TTL_MS = 30_000
-
-    module_function
-
-    def schema_cache_key(tenant_slug, app_slug, table)
-      "#{tenant_slug}/#{app_slug}/#{table}"
-    end
-
-    class SchemaCache
-      Entry = Struct.new(:schema, :expires_at, keyword_init: true)
-
-      def initialize(max_entries: nil, ttl_ms: nil, negative_ttl_ms: nil)
-        @store = {}
-        @max_entries = [1, max_entries.nil? ? DEFAULT_SCHEMA_CACHE_MAX_ENTRIES : max_entries].max
-        @ttl_ms = [1, ttl_ms.nil? ? DEFAULT_SCHEMA_CACHE_TTL_MS : ttl_ms].max
-        @negative_ttl_ms = [0, negative_ttl_ms.nil? ? DEFAULT_SCHEMA_CACHE_NEGATIVE_TTL_MS : negative_ttl_ms].max
-      end
-
-      def size
-        @store.size
-      end
-
-      def get(key)
-        entry = @store[key]
-        return nil if entry.nil?
-
-        if entry.expires_at <= _now_ms
-          @store.delete(key)
-          return nil
-        end
-        # refresh recency: move to end (delete + reinsert)
-        @store.delete(key)
-        @store[key] = entry
-        entry.schema
-      end
-
-      def set(key, schema, ttl_ms = nil)
-        @store.delete(key)
-        @store[key] = Entry.new(schema: schema, expires_at: _now_ms + [1, ttl_ms.nil? ? @ttl_ms : ttl_ms].max)
-        _evict_overflow
-        nil
-      end
-
-      def invalidate(key = nil)
-        if key.nil?
-          @store.clear
-        else
-          @store.delete(key)
-        end
-        nil
-      end
-
-      def get_or_set(key, fresh: nil, ttl_ms: nil)
-        unless fresh
-          cached = get(key)
-          return cached unless cached.nil?
-        end
-        previous = @store[key]
-        begin
-          schema = yield
-        rescue StandardError => e
-          if !previous.nil? && @negative_ttl_ms.positive? && _transient_server_error?(e)
-            @store.delete(key)
-            @store[key] = Entry.new(schema: previous.schema, expires_at: _now_ms + @negative_ttl_ms)
-          end
-          raise
-        end
-        set(key, schema, ttl_ms)
-        schema
-      end
-
-      private
-
-      def _now_ms
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
-      end
-
-      def _transient_server_error?(err)
-        status = err.respond_to?(:status) ? err.status : nil
-        status.is_a?(Integer) && status >= 500
-      end
-
-      def _evict_overflow
-        @store.shift while @store.size > @max_entries # oldest first
-      end
-    end
-  end
-end

data/lib/axhub_sdk/data/where_serializer.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'date'
-require_relative 'errors'
-
-module AxHub
-  module Data
-    # Serialize the predicate DSL into backend filter query params (mirrors node
-    # where-serializer + python where_serializer).
-    #
-    # Each pushable atom becomes column=<op>.<value> (PostgREST-style). Repeated
-    # columns collapse into an array so the transport emits repeated query params
-    # (URI.encode_www_form repeats array-valued keys). Only top-level and(...) of
-    # pushable atoms and bare atoms are accepted; or/not/raw and nested-and raise
-    # ValidationError — this matches the live backend's filter grammar.
-    PUSHABLE_BINARY = %i[eq ne gt gte lt lte like].freeze
-
-    module_function
-
-    def serialize_where(expr)
-      return {} if expr.nil?
-
-      out = {}
-      _collect_pushable_filters(expr, allow_and: true).each do |f|
-        _append_query(out, f[:column], f[:value])
-      end
-      out
-    end
-
-    def _append_query(out, key, value)
-      if !out.key?(key)
-        out[key] = value
-      elsif out[key].is_a?(Array)
-        out[key] << value
-      else
-        out[key] = [out[key], value]
-      end
-    end
-
-    def _collect_pushable_filters(expr, allow_and:)
-      op = expr[:op]
-      if PUSHABLE_BINARY.include?(op)
-        return [{ column: expr[:column], value: "#{op}.#{_stringify(expr[:value])}" }]
-      end
-
-      if op == :in
-        values = expr[:values].map { |v| _stringify(v) }
-        bad = values.find { |v| v.include?(',') }
-        unless bad.nil?
-          raise ValidationError.new(
-            "IN filter values cannot contain commas because the live backend uses comma-separated IN lists (bad value: #{bad})",
-            'filter_in_comma'
-          )
-        end
-        return [{ column: expr[:column], value: "in.#{values.join(',')}" }]
-      end
-
-      if op == :and && allow_and
-        out = []
-        expr[:clauses].each { |clause| out.concat(_collect_pushable_filters(clause, allow_and: false)) }
-        return out
-      end
-
-      # or / not / raw / nested-and all fall through to the rejection below.
-      raise ValidationError.new(
-        "Data where clause '#{op}' cannot be pushed to the live backend; use top-level and(eq/ne/gt/gte/lt/lte/in/like) only",
-        'unsupported_filter'
-      )
-    end
-
-    def _stringify(value)
-      case value
-      when Time then value.iso8601
-      when DateTime, Date then value.iso8601
-      when nil then 'null'
-      when true then 'true'
-      when false then 'false'
-      when String, Integer, Float then value.to_s
-      else JSON.generate(value)
-      end
-    end
-  end
-end

data/lib/axhub_sdk/data.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-# Ergonomic data layer for the AX Hub Ruby SDK.
-#
-# Public surface (mirrors the node `resources/data` layer):
-#
-#   client.tenant(tenant_slug).app(app_slug).data.table(name_or_schema)
-#   client.tenant(tenant_slug).app(app_slug).data.discover(table)
-#
-# returns a DataTableClient with list / list_all / count / get / insert /
-# insert_many / update / delete, plus the predicate DSL (where(col).eq(v) /
-# and_(...) / block form), define_schema(...), and offset-only pagination.
-require_relative 'data/errors'
-require_relative 'data/dsl/schema'
-require_relative 'data/dsl/ops'
-require_relative 'data/dsl/validation'
-require_relative 'data/pagination'
-require_relative 'data/projection'
-require_relative 'data/where_serializer'
-require_relative 'data/schema_cache'
-require_relative 'data/discover'
-require_relative 'data/client'
-
-module AxHub
-  module Data
-    # Fluent scope wrappers so the public chain reads `client.tenant(t).app(a).data`
-    # (mirrors node/python, where `.data` on the app scope yields the ergonomic
-    # AppDataFactory). `client.data` itself stays the operation-id OperationClient.
-    class AppScope
-      attr_reader :data
-
-      def initialize(ergo_data, tenant_slug, app_slug)
-        # `ergo_data` is the single per-client DataClient (memoized on Client), so
-        # its schema cache persists across every tenant().app() chain — node parity.
-        @data = ergo_data.scoped(tenant_slug).app(app_slug)
-      end
-    end
-
-    class TenantScope
-      def initialize(ergo_data, tenant_slug)
-        @ergo_data = ergo_data
-        @tenant_slug = tenant_slug
-      end
-
-      def app(app_slug)
-        AppScope.new(@ergo_data, @tenant_slug, app_slug)
-      end
-    end
-  end
-
-  # --- Ergonomic data layer fluent surface (mirrors node client.tenant().app().data) ---
-  # `client.data` stays the operation-id route-table OperationClient (the
-  # conformance vectors + e2e tests depend on it). The ergonomic data layer is
-  # reached only through the tenant/app fluent chain, exactly as in node/python.
-  class Client
-    # The single per-client ergonomic DataClient, lazily memoized so the schema
-    # cache (TTL/negative-TTL/LRU) survives across tenant().app() chains (mirrors
-    # node, where `data` is one per-SDK DataClient).
-    def ergo_data
-      @ergo_data ||= AxHub::Data::DataClient.new(self, schema_cache: @schema_cache_opt)
-    end
-
-    def tenant(tenant_slug)
-      AxHub::Data::TenantScope.new(ergo_data, tenant_slug)
-    end
-  end
-end