hotkv 1.0.0

data/lib/hotkv/namespaces/admin.rb

@@ -0,0 +1,261 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Namespaces
+    # ACL: users and their permissions (core, not licensed).
+    class ACL
+      def initialize(client)
+        @client = client
+      end
+
+      # Creates or modifies a user. +rules+ are the ACL rule strings
+      # ("on", ">password", "~pattern", "+get", ...); every rule applies or
+      # none does.
+      def setuser(username, *rules)
+        @client.invoke("ACL", "SETUSER", username, *rules.flatten) { |r| r == "OK" }
+      end
+
+      # Hash of the user's flags, passwords (SHA-256 hex), commands, keys,
+      # channels, databases and selectors; nil when the user does not exist.
+      def getuser(username)
+        @client.invoke("ACL", "GETUSER", username) { |r| r.nil? ? nil : hash_of(r) }
+      end
+
+      # Deletes users and disconnects their clients. Returns how many existed.
+      def deluser(*usernames)
+        @client.invoke("ACL", "DELUSER", *usernames.flatten)
+      end
+
+      # Every user as an ACL file line.
+      def list
+        @client.invoke("ACL", "LIST")
+      end
+
+      def users
+        @client.invoke("ACL", "USERS")
+      end
+
+      # The user of the connection that runs it.
+      def whoami
+        @client.invoke("ACL", "WHOAMI")
+      end
+
+      # The categories, or the commands in +category+.
+      def cat(category = nil)
+        category ? @client.invoke("ACL", "CAT", category) : @client.invoke("ACL", "CAT")
+      end
+
+      # A random password of +bits+ bits (default 256) as hex.
+      def genpass(bits = nil)
+        bits ? @client.invoke("ACL", "GENPASS", bits) : @client.invoke("ACL", "GENPASS")
+      end
+
+      # Denied commands and failed logins (the newest +count+ entries).
+      def log(count = nil)
+        count ? @client.invoke("ACL", "LOG", count) : @client.invoke("ACL", "LOG")
+      end
+
+      def log_reset
+        @client.invoke("ACL", "LOG", "RESET") { |r| r == "OK" }
+      end
+
+      # "OK" when +username+ may run the command, else the reason.
+      def dryrun(username, *command)
+        @client.invoke("ACL", "DRYRUN", username, *command.flatten)
+      end
+
+      private
+
+      def hash_of(reply)
+        reply.is_a?(Hash) ? reply : reply.each_slice(2).to_h
+      end
+    end
+
+    # Multi-tenancy (TENANT.*, licensed).
+    class Tenant
+      def initialize(client)
+        @client = client
+      end
+
+      # Creates tenant +id+ with display +name+ and optional limits.
+      def create(id, name, max_memory: nil, max_keys: nil, max_connections: nil, max_commands_sec: nil,
+                 max_databases: nil, max_egress: nil)
+        args = ["TENANT.CREATE", id, name]
+        args.push("MAX_MEMORY", max_memory) if max_memory
+        args.push("MAX_KEYS", max_keys) if max_keys
+        args.push("MAX_CONNECTIONS", max_connections) if max_connections
+        args.push("MAX_COMMANDS_SEC", max_commands_sec) if max_commands_sec
+        args.push("MAX_DATABASES", max_databases) if max_databases
+        args.push("MAX_EGRESS", max_egress) if max_egress
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def drop(id)
+        @client.invoke("TENANT.DROP", id) { |r| r == 1 || r == "OK" }
+      end
+
+      # Tenant ids.
+      def list
+        @client.invoke("TENANT.LIST")
+      end
+
+      # Hash with :id, :name, :state and the usage counters.
+      def info(id)
+        @client.invoke("TENANT.INFO", id) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      # Hash of usage counters and limits (:memory_bytes, :memory_limit, ...).
+      def stats(id)
+        @client.invoke("TENANT.STATS", id) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      def suspend(id)
+        @client.invoke("TENANT.SUSPEND", id) { |r| r == "OK" }
+      end
+
+      def resume(id)
+        @client.invoke("TENANT.RESUME", id) { |r| r == "OK" }
+      end
+
+      # Binds ACL user +username+ to tenant +tenant_id+.
+      def bind(tenant_id, username)
+        @client.invoke("TENANT.BIND", tenant_id, username) { |r| r == "OK" }
+      end
+
+      def unbind(tenant_id, username)
+        @client.invoke("TENANT.UNBIND", tenant_id, username) { |r| r == 1 || r == "OK" }
+      end
+    end
+
+    # Enterprise IAM roles and sessions (IAM.*, licensed).
+    class IAM
+      def initialize(client)
+        @client = client
+      end
+
+      # +permissions+ is a comma separated String or an Array of command
+      # patterns; :key_prefixes restricts the role to keys with those prefixes.
+      def role_create(name, permissions, key_prefixes: nil, rate_limit: nil, memory_quota: nil)
+        args = ["IAM.ROLE.CREATE", name, Array(permissions).join(",")]
+        args.push("KEY_PREFIXES", Array(key_prefixes).join(",")) if key_prefixes
+        args.push("RATE_LIMIT", rate_limit) if rate_limit
+        args.push("MEMORY_QUOTA", memory_quota) if memory_quota
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def role_delete(name)
+        @client.invoke("IAM.ROLE.DELETE", name) { |r| r == "OK" }
+      end
+
+      def role_list
+        @client.invoke("IAM.ROLE.LIST")
+      end
+
+      # Hash with :name, :permissions (comma joined String), :rate_limit and
+      # :memory_quota.
+      def role_info(name)
+        @client.invoke("IAM.ROLE.INFO", name) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      def user_assign(username, rolename)
+        @client.invoke("IAM.USER.ASSIGN", username, rolename) { |r| r == "OK" }
+      end
+
+      # Active sessions as an Array of Hashes (:id, :username, :commands).
+      def session_list
+        @client.invoke("IAM.SESSION.LIST") { |r| r.map { |s| Commands::Support.pairs_to_h(s) } }
+      end
+
+      def session_kill(session_id)
+        @client.invoke("IAM.SESSION.KILL", session_id) { |r| r == "OK" }
+      end
+
+      # Authenticates +username+ against +source+ ("ldap", "oidc", "saml", or
+      # anything else for local auth). Returns the session id.
+      def auth(source, username, credential)
+        @client.invoke("IAM.AUTH", source, username, credential)
+      end
+    end
+
+    # Tamper evident audit log (AUDIT.*, licensed).
+    class Audit
+      def initialize(client)
+        @client = client
+      end
+
+      # Hash with :total_entries, :file_size_bytes, :chain_valid (Integer
+      # 0/1) and :last_sequence.
+      def info
+        @client.invoke("AUDIT.INFO") { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      # Verifies the whole hash chain. Returns the server's status line
+      # ("OK chain verified"); raises ServerError when tampering is detected.
+      def verify
+        @client.invoke("AUDIT.VERIFY")
+      end
+
+      # Writes the log to +file+ on the server (+format+ "jsonl", "csv" or "cef").
+      def export(file, format: nil)
+        args = ["AUDIT.EXPORT", file]
+        args.push("FORMAT", format) if format
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      # Renames the current log with a timestamp suffix and starts a new one.
+      def rotate
+        @client.invoke("AUDIT.ROTATE") { |r| r == "OK" }
+      end
+    end
+
+    # Encryption at rest (ENCRYPTION.*, licensed).
+    class Encryption
+      def initialize(client)
+        @client = client
+      end
+
+      # Hash with :enabled (Integer 0/1), :algorithm and :provider.
+      def info
+        @client.invoke("ENCRYPTION.INFO") { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      # Switches snapshots to the 32 byte key in +new_key_file+ (a path on
+      # the server).
+      def rotate(new_key_file)
+        @client.invoke("ENCRYPTION.ROTATE", new_key_file) { |r| r == "OK" }
+      end
+
+      # True when the encrypted file at +file+ (a server path) is intact.
+      def verify(file)
+        @client.invoke("ENCRYPTION.VERIFY", file) { |r| r == 1 }
+      end
+    end
+
+    # Replication control (REPLICATION.*, licensed).
+    class Replication
+      def initialize(client)
+        @client = client
+      end
+
+      # Hash with :role, :state, :repl_offset, :connected_replicas, ...
+      def info
+        @client.invoke("REPLICATION.INFO") { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      # Stops sending (primary) or applying (replica) writes.
+      def pause
+        @client.invoke("REPLICATION.PAUSE") { |r| r == "OK" }
+      end
+
+      def resume
+        @client.invoke("REPLICATION.RESUME") { |r| r == "OK" }
+      end
+
+      # Promotes this replica to primary (without cluster mode).
+      def failover
+        @client.invoke("REPLICATION.FAILOVER") { |r| r == "OK" }
+      end
+    end
+  end
+end

data/lib/hotkv/namespaces/amem.rb

@@ -0,0 +1,172 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Namespaces
+    # AMEM.* (AI agent memory; needs a license that includes the
+    # AgentMemory feature): conversation, semantic, working and episodic
+    # memory, plus cross-memory search. AMEM.SUMMARY.* (the AMemSummary
+    # feature) lives under the nested #summary accessor.
+    class AMem
+      attr_reader :summary
+
+      def initialize(client)
+        @client = client
+        @summary = Summary.new(client)
+      end
+
+      # -- conversation memory --
+
+      def conv_create(session_id, window: nil, ttl: nil)
+        args = ["AMEM.CONV.CREATE", session_id]
+        args.push("WINDOW", window) if window
+        args.push("TTL", ttl) if ttl
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def conv_append(session_id, role, content)
+        @client.invoke("AMEM.CONV.APPEND", session_id, role, content) { |r| r == "OK" }
+      end
+
+      def conv_get(session_id)
+        @client.invoke("AMEM.CONV.GET", session_id) { |r| r.map { |row| labeled(row, %i[role content]) } }
+      end
+
+      def conv_window(session_id, n)
+        @client.invoke("AMEM.CONV.WINDOW", session_id, n) { |r| r.map { |row| labeled(row, %i[role content]) } }
+      end
+
+      def conv_clear(session_id)
+        @client.invoke("AMEM.CONV.CLEAR", session_id) { |r| r == 1 }
+      end
+
+      def conv_drop(session_id)
+        @client.invoke("AMEM.CONV.DROP", session_id) { |r| r == 1 }
+      end
+
+      # -- semantic memory (per-agent vector store) --
+
+      def sem_create(agent_id, dimensions)
+        @client.invoke("AMEM.SEM.CREATE", agent_id, dimensions) { |r| r == "OK" }
+      end
+
+      def sem_store(agent_id, key, content, vector, ttl: nil)
+        args = ["AMEM.SEM.STORE", agent_id, key, content, *Wire.finite_vector(vector)]
+        args.push("TTL", ttl) if ttl
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def sem_recall(agent_id, k, vector)
+        @client.invoke("AMEM.SEM.RECALL", agent_id, k, *Wire.finite_vector(vector)) do |r|
+          r.map { |row| labeled(row, %i[key content similarity], float_fields: %i[similarity]) }
+        end
+      end
+
+      def sem_forget(agent_id, key)
+        @client.invoke("AMEM.SEM.FORGET", agent_id, key) { |r| r == 1 }
+      end
+
+      def sem_list(agent_id)
+        @client.invoke("AMEM.SEM.LIST", agent_id)
+      end
+
+      # -- working memory (per-session scratch key/value) --
+
+      def work_set(session_id, key, value, ttl: nil)
+        args = ["AMEM.WORK.SET", session_id, key, value]
+        args.push("TTL", ttl) if ttl
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def work_get(session_id, key)
+        @client.invoke("AMEM.WORK.GET", session_id, key)
+      end
+
+      def work_del(session_id, key)
+        @client.invoke("AMEM.WORK.DEL", session_id, key) { |r| r == 1 }
+      end
+
+      def work_clear(session_id)
+        @client.invoke("AMEM.WORK.CLEAR", session_id) { |r| r == 1 }
+      end
+
+      def work_list(session_id)
+        @client.invoke("AMEM.WORK.LIST", session_id)
+      end
+
+      # -- episodic memory (append only event log) --
+
+      def epis_log(agent_id, event_type, content, metadata: nil)
+        args = ["AMEM.EPIS.LOG", agent_id, event_type, content]
+        args.push("METADATA", metadata) if metadata
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def epis_query(agent_id, type: nil, from: nil, to: nil, limit: nil)
+        args = ["AMEM.EPIS.QUERY", agent_id]
+        args.push("TYPE", type) if type
+        args.push("FROM", from) if from
+        args.push("TO", to) if to
+        args.push("LIMIT", limit) if limit
+        @client.invoke(*args) { |r| r.map { |row| labeled(row, %i[type content metadata timestamp]) } }
+      end
+
+      def epis_clear(agent_id)
+        @client.invoke("AMEM.EPIS.CLEAR", agent_id) { |r| r == 1 }
+      end
+
+      def epis_stats(agent_id)
+        @client.invoke("AMEM.EPIS.STATS", agent_id) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      # -- cross-memory search (semantic + episodic + working together) --
+
+      def search(agent_id, k, vector)
+        @client.invoke("AMEM.SEARCH", agent_id, k, *Wire.finite_vector(vector)) do |r|
+          r.map { |row| labeled(row, %i[source key content similarity], float_fields: %i[similarity]) }
+        end
+      end
+
+      private
+
+      # A "labeled flat array" reply looks like ["role", <role>, "content",
+      # <content>]: fixed label tokens paired with their values. Unwraps
+      # it into a Hash keyed by +fields+, in the order the server documents.
+      def labeled(row, fields, float_fields: [])
+        h = {}
+        fields.each_with_index { |f, i| h[f] = row[(i * 2) + 1] }
+        float_fields.each { |f| h[f] = Wire.parse_float(h[f]) }
+        h
+      end
+
+      # AMEM.SUMMARY.* (needs the AMemSummary license feature).
+      class Summary
+        def initialize(client)
+          @client = client
+        end
+
+        def set(agent_id, summary_text)
+          @client.invoke("AMEM.SUMMARY.SET", agent_id, summary_text)
+        end
+
+        def append(agent_id, extra)
+          @client.invoke("AMEM.SUMMARY.APPEND", agent_id, extra)
+        end
+
+        def get(agent_id)
+          @client.invoke("AMEM.SUMMARY.GET", agent_id) do |r|
+            r.nil? ? nil : { summary: r[0], version: r[1], updated_unix: r[2] }
+          end
+        end
+
+        def drop(agent_id)
+          @client.invoke("AMEM.SUMMARY.DROP", agent_id) { |r| r == 1 }
+        end
+
+        def list
+          @client.invoke("AMEM.SUMMARY.LIST")
+        end
+      end
+    end
+  end
+end