axonbase-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2af53f84385eb0aa349e48950a5ab6e91d8368a918028127f9cd254ec030b14
+  data.tar.gz: db4a5d54e6cedf4a7af3cac044dc40c4e352ada002186d2e69b51f561fb8593d
+SHA512:
+  metadata.gz: 37c471b91d5be964be66b5267cc747209a68aad3ca61568a42422633f3c6cd9eb5ea03e5d81d00646a8cd24eade0dc190dcef74100b4146766d2fe4e7ef9a780
+  data.tar.gz: bf67a5d343902ed310a1485a43b36b9c710a1e057aa2595d18ce9ba1b3a6741e04dc8d04063f88a7ffdb9ad6c0b9c4a1d6867814fa3536c9a4701bfe5309915d

data/lib/axonbase/client.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module AxonBase
+  class Client
+    attr_reader :namespace, :database, :hello
+
+    def self.connect(url, ssl_context: nil)
+      new(WebSocketTransport.new(url, ssl_context: ssl_context))
+    end
+
+    def initialize(transport)
+      @transport = transport
+      @next_id = 1
+      @live_handlers = {}
+      frame = decode(@transport.receive)
+      raise Error, "expected hello as first WebSocket frame" unless frame["hello"].is_a?(Hash)
+      @hello = frame["hello"]
+    end
+
+    def use(namespace, database)
+      result = call("use", [namespace, database])
+      @namespace = result.fetch("namespace", namespace)
+      @database = result.fetch("database", database)
+      result
+    end
+
+    def signin(user, pass, access = nil)
+      credentials = { "user" => user, "pass" => pass }
+      credentials["access"] = access unless access.nil?
+      @token = call("signin", [credentials])
+    end
+
+    def authenticate(token)
+      call("authenticate", [token])
+      @token = token
+      nil
+    end
+
+    def query(sql, vars = nil)
+      call("query", vars.nil? ? [sql] : [sql, vars])
+    end
+
+    def select(target, where = nil); call("select", where.nil? ? [target] : [target, where]); end
+    def create(target, data); call("create", [target, data]); end
+    def insert(table, data); call("insert", [table, data]); end
+    def update(target, data); call("update", [target, data]); end
+    def upsert(target, data); call("upsert", [target, data]); end
+    def delete(target, where = nil); call("delete", where.nil? ? [target] : [target, where]); end
+    def ping; call("ping", []); end
+    def version; call("version", []); end
+    def close; @transport.close; end
+
+    def relate(from, kind, to, data = {})
+      call("relate", [from, kind, to, data])
+    end
+
+    def let_var(name, value)
+      clean = name.start_with?("$") ? name[1..] : name
+      call("let", [clean, value])
+    end
+
+    def unset(name)
+      clean = name.start_with?("$") ? name[1..] : name
+      call("unset", [clean])
+    end
+
+    def begin; call("begin", []); end
+    def commit; call("commit", []); end
+    def cancel; call("cancel", []); end
+
+    def kv_get(ns, db, key); call("kv_get", [ns, db, key]); end
+    def kv_set(ns, db, key, value, ttl = nil); call("kv_set", [ns, db, key, value, ttl]); end
+    def kv_del(ns, db, key); call("kv_del", [ns, db, key]); end
+    def kv_scan(ns, db, prefix); call("kv_scan", [ns, db, prefix]); end
+
+    def live(table, handler, diff = false)
+      id = call("live", [table, diff])
+      @live_handlers[id] = handler
+      id
+    end
+
+    def kill(id)
+      ok = call("kill", [id])
+      @live_handlers.delete(id) if ok
+      ok
+    end
+
+    def certificate_begin(store)
+      result = call("certificate.begin", [{ "store" => store }])
+      {
+        "id" => result["id"],
+        "challenge" => result["challenge"],
+        "expires_at" => result["expires_at"],
+      }
+    end
+
+    def certificate_complete(completion_hash)
+      call("certificate.complete", [completion_hash])
+    end
+
+    private
+
+    def call(method, params)
+      id = @next_id
+      @next_id += 1
+      @transport.send(JSON.generate("id" => id, "method" => method, "params" => params, "version" => PROTOCOL_VERSION))
+      loop do
+        response = decode(@transport.receive)
+        if response.key?("notification")
+          n = response["notification"]
+          handler = @live_handlers[n["id"]]
+          handler&.call(n["id"], n["action"], n["result"])
+          next
+        end
+        next if response["id"] != id
+        raise rpc_error(response["error"]) if response.key?("error")
+        return response["result"]
+      end
+    end
+
+    def decode(frame)
+      JSON.parse(frame)
+    rescue JSON::ParserError
+      raise Error, "invalid JSON-RPC frame"
+    end
+
+    def rpc_error(error)
+      code, message = error.fetch("code", 0), error.fetch("message", "RPC error")
+      case code
+      when -32_002 then AuthError.new(message, code)
+      when -32_009 then ConflictError.new(message, code)
+      when -32_010 then NotLeaderError.new(message, error.fetch("leader", ""), error.fetch("leader_address", ""))
+      when -32_011 then NoQuorumError.new(message, code)
+      when -32_029 then RateLimitError.new(message, code)
+      when -32_600
+        return ProtocolMismatchError.new(message, error.fetch("protocol", 0), error.fetch("version", 0)) if error["kind"] == "PROTOCOL_MISMATCH"
+        Error.new(message, code)
+      else Error.new(message, code)
+      end
+    end
+  end
+end

data/lib/axonbase/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AxonBase
+  class Error < StandardError
+    attr_reader :code
+    def initialize(message, code = nil)
+      super(message)
+      @code = code
+    end
+  end
+
+  class AuthError < Error; end
+  class ConflictError < Error; end
+  class NoQuorumError < Error; end
+  class RateLimitError < Error; end
+
+  class NotLeaderError < Error
+    attr_reader :leader, :leader_address
+    def initialize(message, leader = "", leader_address = "")
+      super(message, -32_010)
+      @leader = leader
+      @leader_address = leader_address
+    end
+  end
+
+  class ProtocolMismatchError < Error
+    attr_reader :protocol, :server_version
+    def initialize(message, protocol, server_version)
+      super(message, -32_600)
+      @protocol = protocol
+      @server_version = server_version
+    end
+  end
+end

data/lib/axonbase/migration.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module AxonBase
+  Migration = Struct.new(:version, :name, :path, :checksum, :sql, keyword_init: true)
+
+  class Migrator
+    DEFAULT_TABLE = "_migration"
+
+    def initialize(axon, table: DEFAULT_TABLE)
+      @axon = axon
+      @table = table
+      @before_hooks = []
+      @after_hooks = []
+    end
+
+    def on_before(&hook)
+      @before_hooks << hook
+      self
+    end
+
+    def on_after(&hook)
+      @after_hooks << hook
+      self
+    end
+
+    def ensure_table
+      @axon.query("DEFINE TABLE #{@table} SCHEMAFULL;" \
+                  "DEFINE FIELD version ON TABLE #{@table} TYPE string;" \
+                  "DEFINE FIELD name ON TABLE #{@table} TYPE string;" \
+                  "DEFINE FIELD checksum ON TABLE #{@table} TYPE string;" \
+                  "DEFINE FIELD applied_at ON TABLE #{@table} TYPE datetime DEFAULT time::now();")
+      nil
+    end
+
+    def applied
+      rows = @axon.query("SELECT version, checksum FROM #{@table} ORDER BY version ASC;")
+      return {} unless rows.is_a?(Array)
+
+      rows.each_with_object({}) do |row, result|
+        next unless row.is_a?(Hash) && row.key?("version") && row.key?("checksum")
+
+        result[row["version"].to_s] = row["checksum"].to_s
+      end
+    rescue Error
+      {}
+    end
+
+    def load(path)
+      if File.file?(path)
+        raise ArgumentError, "not an .axql file: #{path}" unless path.end_with?(".axql")
+
+        return [parse_file(path)]
+      end
+      raise ArgumentError, "migration directory not found: #{path}" unless Dir.exist?(path)
+
+      Dir.glob(File.join(path, "*.axql")).sort.map { |file| parse_file(file) }
+    end
+
+    def status(path)
+      completed = applied
+      load(path).map { |migration| { migration: migration, applied: completed.key?(migration.version) } }
+    end
+
+    def up(path)
+      completed = applied
+      pending = load(path).reject do |migration|
+        checksum = completed[migration.version]
+        next false if checksum.nil?
+
+        raise "migration checksum changed: #{migration.name}" unless checksum == migration.checksum
+
+        true
+      end
+      return [] if pending.empty?
+
+      ensure_table
+      pending.each do |migration|
+        @before_hooks.each { |hook| hook.call(migration) }
+        @axon.query(migration.sql) unless migration.sql.strip.empty?
+        @axon.query(
+          "UPSERT #{@table}:v_#{migration.version} CONTENT { version: $v, name: $n, checksum: $c, applied_at: time::now() }",
+          "v" => migration.version,
+          "n" => migration.name,
+          "c" => migration.checksum
+        )
+        @after_hooks.each { |hook| hook.call(migration) }
+      end
+      pending
+    end
+
+    private
+
+    def parse_file(path)
+      name = File.basename(path, ".axql")
+      Migration.new(
+        version: name.split("_", 2).first,
+        name: name,
+        path: path,
+        checksum: Digest::SHA256.file(path).hexdigest,
+        sql: File.read(path)
+      )
+    rescue Errno::ENOENT, Errno::EACCES => error
+      raise "failed to read migration: #{path}: #{error.message}"
+    end
+  end
+end

data/lib/axonbase/saga_participant_transaction.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AxonBase
+  class SagaParticipantTransaction
+    attr_reader :correlation_id
+
+    def initialize(axon, correlation_id)
+      @axon = axon
+      @correlation_id = correlation_id
+      @begun = false
+      @finished = false
+    end
+
+    def is_begun?
+      @begun
+    end
+
+    def is_finished?
+      @finished
+    end
+
+    def begin
+      raise Error, "Transaction already begun: #{@correlation_id}" if @begun
+
+      @axon.begin
+      @axon.let_var("saga_corr", @correlation_id)
+      @begun = true
+    rescue StandardError
+      @axon.cancel rescue nil
+      raise
+    end
+
+    def step(axonql)
+      assert_active
+      @axon.query(axonql)
+    end
+
+    def commit
+      assert_active
+      @axon.commit
+      @finished = true
+    end
+
+    def rollback
+      return unless @begun && !@finished
+
+      @axon.cancel
+      @finished = true
+    end
+
+    private
+
+    def assert_active
+      raise Error, "Transaction not begun" unless @begun
+      raise Error, "Transaction already finished" if @finished
+    end
+  end
+end

data/lib/axonbase/saga_transaction.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AxonBase
+  class SagaTransaction
+    attr_reader :saga_name, :correlation_id
+
+    def initialize(axon, saga_name, correlation_id)
+      @axon = axon
+      @saga_name = saga_name
+      @correlation_id = correlation_id
+      @begun = false
+      @finished = false
+    end
+
+    def is_begun?
+      @begun
+    end
+
+    def is_finished?
+      @finished
+    end
+
+    def begin
+      raise Error, "Saga already begun: #{@correlation_id}" if @begun
+
+      result = @axon.query("BEGIN SAGA #{escape(@saga_name)} WITH CORRELATION '#{escape(@correlation_id)}'")
+      if result.is_a?(Hash) && result["status"] == "RUNNING"
+        @begun = true
+        return
+      end
+
+      raise Error, "Failed to begin saga: #{result}"
+    end
+
+    def step(axonql)
+      assert_active
+      @axon.let_var("saga_corr", @correlation_id)
+      @axon.query(axonql)
+    end
+
+    def commit
+      assert_active
+      result = @axon.query("COMMIT SAGA #{escape(@saga_name)} WITH CORRELATION '#{escape(@correlation_id)}'")
+      @finished = true
+      raise Error, "Saga commit failed: #{result}" unless result.is_a?(Hash) && result["status"] == "COMMITTED"
+    end
+
+    def rollback
+      return unless @begun && !@finished
+
+      @axon.query("CANCEL SAGA #{escape(@saga_name)} WITH CORRELATION '#{escape(@correlation_id)}'")
+      @finished = true
+    end
+
+    def describe
+      @axon.query("SHOW SAGA TRANSACTION #{escape(@saga_name)} '#{escape(@correlation_id)}'")
+    end
+
+    private
+
+    def assert_active
+      raise Error, "Saga not begun" unless @begun
+      raise Error, "Saga already finished" if @finished
+    end
+
+    def escape(value)
+      value.gsub("\\") { "\\\\\\\\" }.gsub("'") { "''" }
+    end
+  end
+end

data/lib/axonbase/transport.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AxonBase
+  class WebSocketTransport
+    def initialize(url, ssl_context: nil)
+      require "websocket-client-simple"
+      @messages = Queue.new
+      options = ssl_context ? { tls: ssl_context } : {}
+      @socket = WebSocket::Client::Simple.connect(url, options)
+      @socket.on(:message) { |message| @messages << message.data }
+      @socket.on(:error) { |error| @messages << error }
+    end
+
+    def send(message)
+      @socket.send(message)
+    end
+
+    def receive
+      message = @messages.pop
+      raise message if message.is_a?(Exception)
+      message
+    end
+
+    def close
+      @socket.close
+    end
+  end
+end

data/lib/axonbase.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "json"
+require "thread"
+require_relative "axonbase/errors"
+require_relative "axonbase/transport"
+require_relative "axonbase/client"
+require_relative "axonbase/migration"
+require_relative "axonbase/saga_transaction"
+require_relative "axonbase/saga_participant_transaction"
+
+module AxonBase
+  PROTOCOL_VERSION = 1
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: axonbase-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AxonBase
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/axonbase.rb
+- lib/axonbase/client.rb
+- lib/axonbase/errors.rb
+- lib/axonbase/migration.rb
+- lib/axonbase/saga_participant_transaction.rb
+- lib/axonbase/saga_transaction.rb
+- lib/axonbase/transport.rb
+homepage: https://github.com/axonbase/axonbase
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/axonbase/axonbase
+  bug_tracker_uri: https://github.com/axonbase/axonbase/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: AxonBase WebSocket JSON-RPC client
+test_files: []