vertexcache 1.0.0

data/lib/vertexcache/command/impl/del_command.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative '../command_base'
+require_relative '../command_type'
+require_relative '../../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Command
+    module Impl
+      class DelCommand < CommandBase
+        def initialize(key)
+          if key.nil? || key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new("#{VertexCache::Command::CommandType::DEL} command requires a non-empty key")
+          end
+
+          @key = key
+        end
+
+        def build_command
+          "#{VertexCache::Command::CommandType::DEL} #{@key}"
+        end
+
+        def parse_response(body)
+          unless body.strip.casecmp('OK').zero?
+            set_failure("DEL failed: #{body}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vertexcache/command/impl/get_command.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative '../command_base'
+require_relative '../../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Command
+    module Impl
+      class GetCommand < CommandBase
+        attr_reader :value
+
+        def initialize(key)
+          if key.nil? || key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new('GET command requires a non-empty key')
+          end
+          @key = key
+          @value = nil
+        end
+
+        def build_command
+          "GET #{@key}"
+        end
+
+        def parse_response(body)
+          if body.strip.casecmp('(nil)').zero?
+            set_success('No matching key found, +(nil)')
+          elsif body.start_with?('ERR')
+            set_failure("GET failed: #{body}")
+          else
+            @value = body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vertexcache/command/impl/get_secondary_idx_one_command.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative '../command_base'
+require_relative '../../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Command
+    module Impl
+      class GetSecondaryIdxOneCommand < CommandBase
+        attr_reader :value
+
+        def initialize(key)
+          if key.nil? || key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new('GET By Secondary Index (idx1) command requires a non-empty key')
+          end
+          @key = key
+          @value = nil
+        end
+
+        def build_command
+          "GETIDX1 #{@key}"
+        end
+
+        def parse_response(body)
+          if body.strip.casecmp('(nil)').zero?
+            set_success('No matching key found, +(nil)')
+          elsif body.start_with?('ERR')
+            set_failure("GETIDX1 failed: #{body}")
+          else
+            @value = body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vertexcache/command/impl/get_secondary_idx_two_command.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative '../command_base'
+require_relative '../../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Command
+    module Impl
+      class GetSecondaryIdxTwoCommand < CommandBase
+        attr_reader :value
+
+        def initialize(key)
+          if key.nil? || key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new('GET By Secondary Index (idx2) command requires a non-empty key')
+          end
+          @key = key
+          @value = nil
+        end
+
+        def build_command
+          "GETIDX2 #{@key}"
+        end
+
+        def parse_response(body)
+          if body.strip.casecmp('(nil)').zero?
+            set_success('No matching key found, +(nil)')
+          elsif body.start_with?('ERR')
+            set_failure("GETIDX2 failed: #{body}")
+          else
+            @value = body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vertexcache/command/impl/ping_command.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative '../command_base'
+
+module VertexCache
+  module Command
+    module Impl
+      class PingCommand < CommandBase
+        def build_command
+          'PING'
+        end
+
+        def parse_response(body)
+          if body.nil? || body.strip.empty? || body.strip.downcase != 'pong'
+            set_failure('PONG not received')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vertexcache/command/impl/set_command.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative '../command_base'
+require_relative '../command_type'
+require_relative '../../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Command
+    module Impl
+      class SetCommand < CommandBase
+        def initialize(primary_key, value, secondary_key = nil, tertiary_key = nil)
+          if primary_key.nil? || primary_key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new('Missing Primary Key')
+          end
+
+          if value.nil? || value.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new('Missing Value')
+          end
+
+          if !secondary_key.nil? && secondary_key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new("Secondary key can't be empty when used")
+          end
+
+          if secondary_key && !secondary_key.strip.empty? && tertiary_key && tertiary_key.strip.empty?
+            raise VertexCache::Model::VertexCacheSdkException.new("Tertiary key can't be empty when used")
+          end
+
+          @primary_key = primary_key
+          @value = value
+          @secondary_key = secondary_key
+          @tertiary_key = tertiary_key
+        end
+
+        def build_command
+          parts = [
+            VertexCache::Command::CommandType::SET,
+            @primary_key,
+            @value
+          ]
+
+          if @secondary_key && !@secondary_key.strip.empty?
+            parts << VertexCache::Command::CommandType::IDX1
+            parts << @secondary_key
+          end
+
+          if @tertiary_key && !@tertiary_key.strip.empty?
+            parts << VertexCache::Command::CommandType::IDX2
+            parts << @tertiary_key
+          end
+
+          parts.join(CommandBase::COMMAND_SPACER)
+        end
+
+        def parse_response(body)
+          if body.strip.casecmp('OK').zero?
+            set_success
+          else
+            set_failure('OK Not received')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vertexcache/model/client_option.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ------------------------------------------------------------------------------
+
+require_relative 'encryption_mode'
+require 'vertexcache/comm/message_codec'
+require 'vertexcache/comm/key_parser_helper'
+require 'vertexcache/model/vertex_cache_sdk_exception'
+require 'base64'
+
+module VertexCache
+  module Model
+    class ClientOption
+      DEFAULT_CLIENT_ID = 'sdk-client'
+      DEFAULT_HOST = '127.0.0.1'
+      DEFAULT_PORT = 50505
+      DEFAULT_READ_TIMEOUT = 3000
+      DEFAULT_CONNECT_TIMEOUT = 3000
+
+      attr_accessor :client_id,
+                    :client_token,
+                    :server_host,
+                    :server_port,
+                    :enable_tls_encryption,
+                    :tls_certificate,
+                    :verify_certificate,
+                    :encryption_mode,
+                    :encrypt_with_public_key,
+                    :encrypt_with_shared_key,
+                    :public_key,
+                    :shared_encryption_key,
+                    :read_timeout,
+                    :connect_timeout
+
+      def initialize
+        @client_id = DEFAULT_CLIENT_ID
+        @client_token = nil
+        @server_host = DEFAULT_HOST
+        @server_port = DEFAULT_PORT
+        @enable_tls_encryption = false
+        @tls_certificate = nil
+        @verify_certificate = false
+        @encryption_mode = EncryptionMode::NONE
+        @encrypt_with_public_key = false
+        @encrypt_with_shared_key = false
+        @public_key = nil
+        @shared_encryption_key = nil
+        @read_timeout = DEFAULT_READ_TIMEOUT
+        @connect_timeout = DEFAULT_CONNECT_TIMEOUT
+      end
+
+      def get_client_id
+        @client_id.nil? ? '' : @client_id
+      end
+
+      def get_client_token
+        @client_token.nil? ? '' : @client_token
+      end
+
+      def build_ident_command
+        "IDENT {\"client_id\":\"#{get_client_id}\", \"token\":\"#{get_client_token}\"}"
+      end
+
+      def resolve_protocol_version
+        case @encryption_mode
+        when EncryptionMode::ASYMMETRIC
+          VertexCache::Comm::MessageCodec::PROTOCOL_VERSION_RSA_PKCS1
+        when EncryptionMode::SYMMETRIC
+          VertexCache::Comm::MessageCodec::PROTOCOL_VERSION_AES_GCM
+        else
+          VertexCache::Comm::MessageCodec::DEFAULT_PROTOCOL_VERSION
+        end
+      end
+
+      def public_key_as_object
+        raise VertexCache::Model::VertexCacheSdkException.new('Missing public key for asymmetric encryption') if @public_key.nil?
+
+        begin
+          OpenSSL::PKey.read(Base64.decode64(@public_key))
+        rescue
+          raise VertexCache::Model::VertexCacheSdkException.new('Failed to parse RSA public key from PEM')
+        end
+      end
+
+      def shared_encryption_key_as_bytes
+        raise VertexCache::Model::VertexCacheSdkException.new('Missing shared encryption key for symmetric mode') if @shared_encryption_key.nil?
+
+        begin
+          Base64.strict_decode64(@shared_encryption_key)
+        rescue
+          raise VertexCache::Model::VertexCacheSdkException.new('Invalid shared key format')
+        end
+      end
+
+      def public_key=(pem)
+        begin
+          OpenSSL::PKey::RSA.new(pem)
+        rescue OpenSSL::PKey::RSAError => e
+          raise VertexCache::Model::VertexCacheSdkException.new("Invalid public key: #{e.message}")
+        end
+        @public_key = pem
+      end
+
+      def shared_encryption_key=(key)
+        begin
+          decoded = Base64.strict_decode64(key)
+          raise unless decoded.bytesize == 32
+        rescue
+          raise VertexCache::Model::VertexCacheSdkException.new('Invalid shared key: must be 32 bytes base64')
+        end
+        @shared_encryption_key = key
+      end
+    end
+  end
+end

data/lib/vertexcache/model/command_result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+module VertexCache
+  module Model
+    class CommandResult
+      attr_reader :success, :message
+
+      def initialize(success, message)
+        @success = success
+        @message = message
+      end
+
+      def success?
+        @success
+      end
+
+      def error?
+        !@success
+      end
+    end
+  end
+end

data/lib/vertexcache/model/encryption_mode.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ------------------------------------------------------------------------------
+
+module VertexCache
+  module Model
+    module EncryptionMode
+      # No encryption is applied; data is sent in plaintext.
+      NONE = 'NONE'
+
+      # Uses public/private key encryption (e.g., RSA).
+      ASYMMETRIC = 'ASYMMETRIC'
+
+      # Uses a shared secret key (e.g., AES-GCM) for encryption.
+      SYMMETRIC = 'SYMMETRIC'
+    end
+  end
+end

data/lib/vertexcache/model/get_result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative 'command_result'
+
+module VertexCache
+  module Model
+    class GetResult < CommandResult
+      attr_reader :value
+
+      def initialize(success, message, value)
+        super(success, message)
+        @value = value
+      end
+    end
+  end
+end

data/lib/vertexcache/model/vertex_cache_sdk_exception.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ------------------------------------------------------------------------------
+
+module VertexCache
+  module Model
+    class VertexCacheSdkException < StandardError; end
+  end
+end
+

data/lib/vertexcache/version.rb

@@ -0,0 +1,3 @@
+module Vertexcache
+  VERSION = "1.0.0"
+end

data/lib/vertexcache_sdk.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# ------------------------------------------------------------------------------
+# Copyright 2025 to Present, Jason Lam - VertexCache (https://github.com/vertexcache/vertexcache)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# ------------------------------------------------------------------------------
+
+require_relative 'vertexcache/version'
+require_relative 'vertexcache/comm/client_connector'
+require_relative 'vertexcache/command/impl/ping_command'
+require_relative 'vertexcache/command/impl/set_command'
+require_relative 'vertexcache/command/impl/del_command'
+require_relative 'vertexcache/command/impl/get_command'
+require_relative 'vertexcache/command/impl/get_secondary_idx_one_command'
+require_relative 'vertexcache/command/impl/get_secondary_idx_two_command'
+require_relative 'vertexcache/model/command_result'
+require_relative 'vertexcache/model/get_result'
+
+module VertexCache
+  class VertexCacheSDK
+    def initialize(client_option)
+      @client_connector = VertexCache::Comm::ClientConnector.new(client_option)
+    end
+
+    def open_connection
+      @client_connector.connect
+    end
+
+    def close
+      @client_connector.close
+    end
+
+    def is_connected?
+      @client_connector.connected?
+    end
+
+    def ping
+      cmd = VertexCache::Command::Impl::PingCommand.new.execute(@client_connector)
+      VertexCache::Model::CommandResult.new(cmd.success?, cmd.get_status_message)
+    end
+
+    def set(key, value, secondary_key = nil, tertiary_key = nil)
+      cmd = VertexCache::Command::Impl::SetCommand.new(key, value, secondary_key, tertiary_key).execute(@client_connector)
+      VertexCache::Model::CommandResult.new(cmd.success?, cmd.get_status_message)
+    end
+
+    def del(key)
+      cmd = VertexCache::Command::Impl::DelCommand.new(key).execute(@client_connector)
+      VertexCache::Model::CommandResult.new(cmd.success?, cmd.get_status_message)
+    end
+
+    def get(key)
+      cmd = VertexCache::Command::Impl::GetCommand.new(key).execute(@client_connector)
+      VertexCache::Model::GetResult.new(cmd.success?, cmd.get_status_message, cmd.value)
+    end
+
+    def get_by_secondary_index(key)
+      cmd = VertexCache::Command::Impl::GetSecondaryIdxOneCommand.new(key).execute(@client_connector)
+      VertexCache::Model::GetResult.new(cmd.success?, cmd.get_status_message, cmd.value)
+    end
+
+    def get_by_tertiary_index(key)
+      cmd = VertexCache::Command::Impl::GetSecondaryIdxTwoCommand.new(key).execute(@client_connector)
+      VertexCache::Model::GetResult.new(cmd.success?, cmd.get_status_message, cmd.value)
+    end
+  end
+end