axhub-sdk 0.2.0 → 0.3.0

data/lib/axhub_sdk/data/dsl/ops.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative 'schema'
+require_relative '../errors'
+
+module AxHub
+  module Data
+    # Predicate DSL: where(col).eq(v), and_(...), or_/not_/raw plus LIKE escaping
+    # and ReDoS guards (mirrors node/python dsl/ops).
+    #
+    # Query expressions are plain symbol-keyed Hashes:
+    #   { op: :eq|:ne|:gt|:gte|:lt|:lte|:like, column: "c", value: v }
+    #   { op: :in, column: "c", values: [...] }
+    #   { op: :and|:or, clauses: [...] }
+    #   { op: :not, clause: expr }
+    #   { op: :raw, sql: "...", params?: [...] }
+    # Only and(eq/ne/gt/gte/lt/lte/in/like) and bare atoms are pushable to the
+    # live backend; or/not/raw raise in the where-serializer (mirrors node).
+    MAX_LIKE_PATTERN_LENGTH = 1024
+    MAX_CONSECUTIVE_WILDCARDS = 4
+    MAX_LIKE_ALTERNATION_SEGMENTS = 6
+
+    ESCAPE_LIKE_RE = /[\\%_]/
+
+    module_function
+
+    def escape_like(value)
+      return value if value == ''
+
+      value.gsub(ESCAPE_LIKE_RE) { |m| "\\#{m}" }
+    end
+
+    # Reject LIKE patterns that translate to catastrophic-backtracking regex
+    # shapes (mirrors node assertSafeLikePattern).
+    def assert_safe_like_pattern(pattern)
+      if pattern.length > MAX_LIKE_PATTERN_LENGTH
+        raise ValidationError.new("LIKE pattern exceeds #{MAX_LIKE_PATTERN_LENGTH} chars; refuse to compile", 'like_pattern_too_long')
+      end
+
+      run_of_wildcards = 0
+      segments = 0
+      i = 0
+      n = pattern.length
+      while i < n
+        ch = pattern[i]
+        if ch == '\\'
+          i += 2
+          run_of_wildcards = 0
+          next
+        end
+        if ch == '%'
+          run_of_wildcards += 1
+          if run_of_wildcards >= MAX_CONSECUTIVE_WILDCARDS
+            raise ValidationError.new("LIKE pattern has #{run_of_wildcards} consecutive '%'; refuse to compile (ReDoS guard)", 'like_pattern_redos')
+          end
+        else
+          segments += 1 if run_of_wildcards == 1
+          run_of_wildcards = 0
+        end
+        i += 1
+      end
+      if segments > MAX_LIKE_ALTERNATION_SEGMENTS
+        raise ValidationError.new("LIKE pattern has #{segments} '%X%' alternation segments; refuse to compile (ReDoS guard)", 'like_pattern_redos')
+      end
+    end
+
+    def raw(sql, params = nil)
+      params.nil? ? { op: :raw, sql: sql } : { op: :raw, sql: sql, params: params }
+    end
+
+    def and_(*clauses)
+      { op: :and, clauses: clauses }
+    end
+
+    def or_(*clauses)
+      { op: :or, clauses: clauses }
+    end
+
+    def not_(clause)
+      { op: :not, clause: clause }
+    end
+
+    # Start a predicate for a column. Accepts a DataColumn, a String, or a Symbol.
+    #
+    #   where(:status).eq("paid")
+    #   where("status").eq("paid")
+    #   where(schema.cols["status"]).eq("paid")
+    #
+    # Block form (idiomatic Ruby): yields the builder and returns its result, so
+    # the bare-atom expr can be written without a trailing chain.
+    #
+    #   where(:status) { |c| c.eq("paid") }
+    def where(column)
+      name = column.is_a?(DataColumn) ? column.name : column.to_s
+      builder = WhereBuilder.new(name)
+      return yield(builder) if block_given?
+
+      builder
+    end
+
+    class LikeBuilder
+      def initialize(name)
+        @name = name
+      end
+
+      def contains(value)
+        { op: :like, column: @name, value: "%#{Data.escape_like(value)}%" }
+      end
+
+      def starts_with(value)
+        { op: :like, column: @name, value: "#{Data.escape_like(value)}%" }
+      end
+
+      def ends_with(value)
+        { op: :like, column: @name, value: "%#{Data.escape_like(value)}" }
+      end
+
+      def raw(value)
+        Data.assert_safe_like_pattern(value)
+        { op: :like, column: @name, value: value }
+      end
+    end
+
+    class WhereBuilder
+      attr_reader :like
+
+      def initialize(name)
+        @name = name
+        @like = LikeBuilder.new(name)
+      end
+
+      def eq(value)  = _binary(:eq, value)
+      def ne(value)  = _binary(:ne, value)
+      def gt(value)  = _binary(:gt, value)
+      def gte(value) = _binary(:gte, value)
+      def lt(value)  = _binary(:lt, value)
+      def lte(value) = _binary(:lte, value)
+
+      def in_(values)
+        { op: :in, column: @name, values: values.to_a }
+      end
+
+      private
+
+      def _binary(op, value)
+        { op: op, column: @name, value: value }
+      end
+    end
+  end
+end

data/lib/axhub_sdk/data/dsl/schema.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module AxHub
+  module Data
+    # Schema definitions and define_schema (mirrors node/python dsl/schema).
+    #
+    # Column defs are either a primitive type string ("uuid" | "string" |
+    # "number" | "integer" | "boolean" | "timestamp" | "json") or an enum
+    # descriptor { type: "enum", values: [...] }. define_schema builds the `cols`
+    # accessor map used by the where(schema.cols["x"]) typed DSL path.
+    DataColumn = Struct.new(:table, :name, :definition) do
+      def initialize(table:, name:, definition:)
+        super(table, name, definition)
+      end
+    end
+
+    class DataTableSchema
+      attr_reader :table, :columns, :cols, :validate
+
+      def initialize(table:, columns:, cols:, validate: nil)
+        @table = table
+        @columns = columns
+        @cols = cols
+        @validate = validate
+        freeze
+      end
+    end
+
+    module_function
+
+    # Define a data table schema. Two call shapes mirror node's two overloads:
+    #   define_schema("orders", { "id" => "uuid", "total" => "number" })
+    #   define_schema({ "table" => "orders", "columns" => {...} }, validate: ...)
+    # An existing DataTableSchema is re-wrapped, optionally attaching `validate`.
+    def define_schema(table_or_input, columns = nil, validate: nil)
+      if table_or_input.is_a?(DataTableSchema)
+        return DataTableSchema.new(
+          table: table_or_input.table,
+          columns: table_or_input.columns,
+          cols: table_or_input.cols,
+          validate: validate.nil? ? table_or_input.validate : validate
+        )
+      end
+
+      if table_or_input.is_a?(Hash)
+        h = _stringify_keys(table_or_input)
+        table = h['table']
+        shape = _stringify_keys(h['columns'])
+      else
+        table = table_or_input
+        raise ArgumentError, 'define_schema requires columns when called with a table name' if columns.nil?
+
+        shape = _stringify_keys(columns)
+      end
+
+      cols = shape.each_with_object({}) do |(name, definition), acc|
+        acc[name] = DataColumn.new(table: table, name: name, definition: definition)
+      end
+      DataTableSchema.new(table: table, columns: shape, cols: cols, validate: validate)
+    end
+
+    def _stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+  end
+end

data/lib/axhub_sdk/data/dsl/validation.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'schema'
+require_relative '../errors'
+
+module AxHub
+  module Data
+    # Optional schema validation hook (mirrors node dsl/zod + python validation).
+    #
+    # The SDK duck-types a zod/dry-validation-style validator so the validation
+    # library stays an optional dependency and is never required. A validator is
+    # "schema-like" if it responds to `safe_parse` (or `safeParse`). On `update`
+    # a `partial` variant is used when available.
+    module_function
+
+    def validator_like?(value)
+      !value.nil? && (value.respond_to?(:safe_parse) || value.respond_to?(:safeParse))
+    end
+
+    def _safe_parse(validator, data)
+      validator.respond_to?(:safe_parse) ? validator.safe_parse(data) : validator.safeParse(data)
+    end
+
+    # Validate `data` against schema.validate before any network request. `mode`
+    # is "insert" or "update" (update uses `partial` when available).
+    def run_schema_validation(schema, data, mode)
+      validator = schema&.validate
+      return if validator.nil?
+
+      unless validator_like?(validator)
+        raise AxHub::Error.new(
+          category: 'configuration', code: 'validator_missing',
+          message: 'define_schema validate option requires a schema-like object with safe_parse'
+        )
+      end
+
+      effective = validator
+      effective = validator.partial if mode == 'update' && validator.respond_to?(:partial)
+      result = _safe_parse(effective, data)
+
+      success = _read(result, :success)
+      return if success
+
+      error = _read(result, :error)
+      issues = _read(error, :issues) || []
+      count = issues.empty? ? 1 : issues.length
+      raise ValidationError.new("#{count} validation failure#{count == 1 ? '' : 's'} before network request", 'validation_failed')
+    end
+
+    # Read an attribute from either a duck-typed object or a Hash.
+    def _read(obj, key)
+      return nil if obj.nil?
+      return obj.public_send(key) if obj.respond_to?(key)
+      return obj[key] if obj.is_a?(Hash) && obj.key?(key)
+      return obj[key.to_s] if obj.is_a?(Hash) && obj.key?(key.to_s)
+
+      nil
+    end
+  end
+end

data/lib/axhub_sdk/data/errors.rb

@@ -0,0 +1,48 @@
+# 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
+  end
+end

data/lib/axhub_sdk/data/pagination.rb

@@ -0,0 +1,100 @@
+# 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

@@ -0,0 +1,50 @@
+# 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

@@ -0,0 +1,105 @@
+# 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

@@ -0,0 +1,84 @@
+# 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