vertexcache 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42487afddcfc0a68780c8ece4a39e7a56d5ce43e9d5119763b8dde6dd0b523c9
+  data.tar.gz: 0ede333ce914f2c1030150613b615bb199d62cbd714464e08a3a0758ed7a9368
+SHA512:
+  metadata.gz: 1617b92ae33cd851091f74eb27304a73713ac061be14a3c7c7124fbd4e847791b4e6b84fe317d0180788a23283276b1520f733639fe1b60f43d34c1b46ad7dfd
+  data.tar.gz: 4bc6093994482292e506b270508c0fa9e8c5796ed6d7ee47ba096ece2cd8d2ea6d293516056ce24b4fbb9f802f02848c52f8eba4b0f1f10282460bb69859910f

data/lib/vertexcache/comm/client_connector.rb

@@ -0,0 +1,111 @@
+# 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 'socket'
+require 'openssl'
+require 'stringio'
+require 'vertexcache/comm/gcm_crypto_helper'
+require 'vertexcache/comm/key_parser_helper'
+require 'vertexcache/comm/message_codec'
+require 'vertexcache/comm/socket_helper'
+require 'vertexcache/model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Comm
+    class ClientConnector
+      attr_reader :connected
+
+      def initialize(client_option)
+        @options = client_option
+        @stream = nil
+        @connected = false
+      end
+
+      def connect
+        @stream = if @options.enable_tls_encryption
+                    SocketHelper.create_secure_socket(@options)
+                  else
+                    SocketHelper.create_socket_non_tls(@options)
+                  end
+
+        writer = @stream.to_io
+        ident_command = @options.build_ident_command
+        payload = encrypt_if_enabled(ident_command.encode('UTF-8'))
+        MessageCodec.write_framed_message(writer, payload)
+        writer.flush
+
+        version, response_payload = MessageCodec.read_framed_message(@stream)
+        raise VertexCache::Model::VertexCacheSdkException, 'Missing payload' if response_payload.nil?
+
+        response = response_payload.force_encoding('UTF-8').strip
+        unless response.start_with?('+OK')
+          raise VertexCache::Model::VertexCacheSdkException, "Authorization failed: #{response}"
+        end
+
+        @connected = true
+        true
+      end
+
+      def send(message)
+        raise VertexCache::Model::VertexCacheSdkException, 'No active connection' unless connected?
+
+        payload = encrypt_if_enabled(message.encode('UTF-8'))
+
+        writer = @stream.to_io
+        MessageCodec.write_framed_message(writer, payload)
+        writer.flush
+
+        _version, response_payload = MessageCodec.read_framed_message(@stream)
+        raise VertexCache::Model::VertexCacheSdkException, 'Missing payload' if response_payload.nil?
+
+        response_payload.force_encoding('UTF-8')
+      end
+
+      def encrypt_if_enabled(plain)
+        case @options.encryption_mode
+        when VertexCache::Model::EncryptionMode::ASYMMETRIC
+          pem = @options.public_key
+          raise VertexCache::Model::VertexCacheSdkException, 'Missing public key' if pem.nil?
+
+          MessageCodec.switch_to_asymmetric
+          KeyParserHelper.encrypt_with_rsa(pem, plain)
+        when VertexCache::Model::EncryptionMode::SYMMETRIC
+          key = @options.shared_encryption_key_as_bytes
+          raise VertexCache::Model::VertexCacheSdkException, 'Missing shared encryption key' if key.nil?
+
+          MessageCodec.switch_to_symmetric
+          GcmCryptoHelper.encrypt(plain, key)
+        else
+          plain
+        end
+      rescue => e
+        raise VertexCache::Model::VertexCacheSdkException, e.message
+      end
+
+      def connected?
+        @connected && !@stream.nil?
+      end
+
+      def close
+        @stream.close if @stream
+        @stream = nil
+        @connected = false
+      end
+    end
+  end
+end

data/lib/vertexcache/comm/gcm_crypto_helper.rb

@@ -0,0 +1,98 @@
+# 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 'openssl'
+require 'base64'
+
+module VertexCache
+  module Comm
+    class GcmCryptoHelper
+      IV_LENGTH = 12
+      TAG_LENGTH = 16
+      KEY_LENGTH = 32
+
+      def self.encrypt(data, key)
+        raise ArgumentError, 'Invalid key length' unless key.bytesize == 16 || key.bytesize == 32
+
+        iv = OpenSSL::Random.random_bytes(IV_LENGTH)
+        cipher = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-gcm")
+        cipher.encrypt
+        cipher.key = key
+        cipher.iv = iv
+
+        ciphertext = cipher.update(data) + cipher.final
+        tag = cipher.auth_tag(TAG_LENGTH)
+
+        iv + ciphertext + tag
+      end
+
+      def self.decrypt(encrypted, key)
+        raise ArgumentError, 'Encrypted data too short' if encrypted.bytesize < IV_LENGTH + TAG_LENGTH
+
+        iv = encrypted[0, IV_LENGTH]
+        tag = encrypted[-TAG_LENGTH, TAG_LENGTH]
+        ciphertext = encrypted[IV_LENGTH..-(TAG_LENGTH + 1)]
+
+        cipher = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-gcm")
+        cipher.decrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+
+        cipher.update(ciphertext) + cipher.final
+      end
+
+      def self.encode_base64_key(key)
+        Base64.strict_encode64(key)
+      end
+
+      def self.decode_base64_key(encoded)
+        Base64.strict_decode64(encoded)
+      end
+
+      def self.generate_base64_key
+        Base64.strict_encode64(OpenSSL::Random.random_bytes(KEY_LENGTH))
+      end
+
+      def self.encrypt_with_iv(data, key, iv)
+        cipher = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-gcm")
+        cipher.encrypt
+        cipher.key = key
+        cipher.iv = iv
+
+        ciphertext = cipher.update(data) + cipher.final
+        tag = cipher.auth_tag(TAG_LENGTH)
+
+        iv + ciphertext + tag
+      end
+
+      def self.decrypt_with_iv(encrypted, key, iv)
+        tag = encrypted[-TAG_LENGTH, TAG_LENGTH]
+        ciphertext = encrypted[IV_LENGTH..-(TAG_LENGTH + 1)]
+
+        cipher = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-gcm")
+        cipher.decrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+
+        cipher.update(ciphertext) + cipher.final
+      end
+    end
+  end
+end

data/lib/vertexcache/comm/key_parser_helper.rb

@@ -0,0 +1,64 @@
+# 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 'base64'
+require 'openssl'
+require 'vertexcache/model/vertex_cache_sdk_exception'
+
+
+module VertexCache
+  module Comm
+    class KeyParserHelper
+      def self.config_public_key_if_enabled(pem_string)
+        begin
+          cleaned = pem_string.gsub(/-----BEGIN PUBLIC KEY-----/, '')
+                              .gsub(/-----END PUBLIC KEY-----/, '')
+                              .gsub(/\s+/, '')
+          decoded = Base64.strict_decode64(cleaned)
+          OpenSSL::PKey.read(decoded)
+          decoded
+        rescue
+          raise VertexCache::Model::VertexCacheSdkException.new('Invalid public key')
+        end
+      end
+
+      def self.config_shared_key_if_enabled(base64_string)
+        begin
+          decoded = Base64.strict_decode64(base64_string)
+          if Base64.strict_encode64(decoded) != base64_string.gsub(/\s+/, '')
+            raise VertexCache::Model::VertexCacheSdkException.new('Invalid shared key')
+          end
+          decoded
+        rescue
+          raise VertexCache::Model::VertexCacheSdkException.new('Invalid shared key')
+        end
+      end
+
+      def self.encrypt_with_rsa(pem_string, plaintext)
+        begin
+          public_key = OpenSSL::PKey::RSA.new(pem_string)
+          cipher_text = public_key.public_encrypt(plaintext, OpenSSL::PKey::RSA::PKCS1_PADDING)
+          cipher_text
+        rescue
+          raise VertexCache::Model::VertexCacheSdkException.new('RSA encryption failed')
+        end
+      end
+
+    end
+  end
+end

data/lib/vertexcache/comm/message_codec.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.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ------------------------------------------------------------------------------
+
+require 'stringio'
+require 'vertexcache/model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Comm
+    class MessageCodec
+      HEADER_LEN = 8
+      MAX_PAYLOAD_SIZE = 10 * 1024 * 1024
+      MAX_MESSAGE_SIZE = 4 * 1024 * 1024
+
+      PROTOCOL_VERSION_RSA_PKCS1 = 0x00000101
+      PROTOCOL_VERSION_AES_GCM   = 0x00000181
+      DEFAULT_PROTOCOL_VERSION   = PROTOCOL_VERSION_RSA_PKCS1
+
+      @@protocol_version = DEFAULT_PROTOCOL_VERSION
+
+      def self.switch_to_asymmetric
+        @@protocol_version = PROTOCOL_VERSION_RSA_PKCS1
+      end
+
+      def self.switch_to_symmetric
+        @@protocol_version = PROTOCOL_VERSION_AES_GCM
+      end
+
+      def self.write_framed_message(io, payload)
+        raise VertexCache::Model::VertexCacheSdkException, 'Payload must be non-empty' if payload.nil? || payload.empty?
+        raise VertexCache::Model::VertexCacheSdkException, 'Payload too large' if payload.bytesize > MAX_MESSAGE_SIZE
+
+        length_prefix = [payload.bytesize].pack('N')         # 4 bytes big-endian
+        version_bytes = [@@protocol_version].pack('N')       # 4 bytes big-endian
+        io.write(length_prefix + version_bytes + payload)
+        io.flush
+      end
+
+      def self.read_framed_message(io)
+        header = io.read(HEADER_LEN)
+        return nil if header.nil? || header.bytesize < HEADER_LEN
+
+        length = header[0, 4].unpack1('N')
+        version = header[4, 4].unpack1('N')
+
+        raise VertexCache::Model::VertexCacheSdkException, 'Invalid message length' if length <= 0 || length > MAX_PAYLOAD_SIZE
+
+        payload = io.read(length)
+        raise VertexCache::Model::VertexCacheSdkException, 'Unexpected end of payload' if payload.nil? || payload.bytesize != length
+
+        [version, payload]
+      end
+
+      def self.hex_dump(payload)
+        io = StringIO.new
+        write_framed_message(io, payload)
+        io.rewind
+        io.read.unpack1('H*').upcase
+      end
+    end
+  end
+end

data/lib/vertexcache/comm/read_write_stream.rb

@@ -0,0 +1,55 @@
+# 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 Comm
+    class ReadWriteStream
+      def initialize(io)
+        @io = io
+      end
+
+      def read(n)
+        @io.read(n)
+      end
+
+      def write(data)
+        @io.write(data)
+      end
+
+      def flush
+        @io.flush
+      end
+
+      def close
+        @io.close
+      end
+
+      def closed?
+        @io.closed?
+      end
+
+      def io
+        @io
+      end
+
+      def to_io
+        @io
+      end
+    end
+  end
+end

data/lib/vertexcache/comm/socket_helper.rb

@@ -0,0 +1,70 @@
+# 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 'socket'
+require 'openssl'
+require_relative 'ssl_helper'
+require_relative 'read_write_stream'
+require_relative '../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Comm
+    class SocketHelper
+      def self.create_secure_socket(options)
+        begin
+          tcp_socket = create_tcp_socket(options)
+          context = if options.verify_certificate
+                      SSLHelper.create_verified_ssl_context(options.tls_certificate)
+                    else
+                      SSLHelper.create_insecure_ssl_context
+                    end
+
+          ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_socket, context)
+          ssl_socket.sync_close = true
+          ssl_socket.connect
+
+          ReadWriteStream.new(ssl_socket)
+        rescue => _
+          raise VertexCache::Model::VertexCacheSdkException.new("Failed to create Secure Socket")
+        end
+      end
+
+      def self.create_socket_non_tls(options)
+        begin
+          tcp_socket = create_tcp_socket(options)
+          ReadWriteStream.new(tcp_socket)
+        rescue => _
+          raise VertexCache::Model::VertexCacheSdkException.new("Failed to create Non Secure Socket")
+        end
+      end
+
+      private
+
+      def self.create_tcp_socket(options)
+        socket = TCPSocket.new(options.server_host, options.server_port)
+        seconds = options.read_timeout.to_i
+        timeval = [seconds, 0].pack("l_2")
+
+        socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, timeval)
+        socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, timeval)
+
+        socket
+      end
+    end
+  end
+end

data/lib/vertexcache/comm/ssl_helper.rb

@@ -0,0 +1,75 @@
+# 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 'openssl'
+require 'vertexcache/model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Comm
+    class SSLHelper
+      # Modern secure cipher suites aligned with server and industry standards
+      MODERN_CIPHERS = [
+        "TLS_AES_128_GCM_SHA256",
+        "TLS_AES_256_GCM_SHA384",
+        "TLS_CHACHA20_POLY1305_SHA256",
+        "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
+        "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
+        "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
+        "TLS_RSA_WITH_AES_128_GCM_SHA256",
+        "TLS_RSA_WITH_AES_256_GCM_SHA384"
+      ].join(":")
+
+      def self.create_verified_ssl_context(pem_cert)
+        raise_invalid_cert unless valid_cert_format?(pem_cert)
+
+        cert = OpenSSL::X509::Certificate.new(pem_cert)
+        store = OpenSSL::X509::Store.new
+        store.add_cert(cert)
+
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.cert_store = store
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        ctx.ciphers = MODERN_CIPHERS
+        ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
+        ctx.max_version = OpenSSL::SSL::TLS1_3_VERSION
+        ctx
+      rescue OpenSSL::X509::CertificateError
+        raise VertexCache::Model::VertexCacheSdkException, 'Failed to parse PEM certificate'
+      rescue => e
+        raise VertexCache::Model::VertexCacheSdkException, 'Failed to build secure socket context'
+      end
+
+      def self.create_insecure_ssl_context
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        ctx.ciphers = MODERN_CIPHERS
+        ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
+        ctx.max_version = OpenSSL::SSL::TLS1_3_VERSION
+        ctx
+      end
+
+      def self.valid_cert_format?(pem_cert)
+        pem_cert && pem_cert.include?("BEGIN CERTIFICATE")
+      end
+
+      def self.raise_invalid_cert
+        raise VertexCache::Model::VertexCacheSdkException, "Invalid certificate format"
+      end
+    end
+  end
+end

data/lib/vertexcache/command/command_base.rb

@@ -0,0 +1,88 @@
+# 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 '../comm/client_connector'
+require_relative '../model/vertex_cache_sdk_exception'
+
+module VertexCache
+  module Command
+    class CommandBase
+      RESPONSE_OK = 'OK'
+      COMMAND_SPACER = ' '
+
+      attr_reader :success, :response, :error
+
+      def execute(client)
+        begin
+          raw = client.send(build_command).strip
+
+          if raw.start_with?('+')
+            @response = raw[1..]
+            parse_response(@response)
+            @success = @error.nil?
+          elsif raw.start_with?('-')
+            @success = false
+            @error = raw[1..]
+          else
+            @success = false
+            @error = "Unexpected response: #{raw}"
+          end
+        rescue VertexCache::Model::VertexCacheSdkException => e
+          @success = false
+          @error = e.message
+        end
+        self
+      end
+
+      def success?
+        @success
+      end
+
+      def get_response
+        @response
+      end
+
+      def get_error
+        @error
+      end
+
+      def get_status_message
+        success? ? get_response : get_error
+      end
+
+      def set_success(response = RESPONSE_OK)
+        @success = true
+        @response = response
+        @error = nil
+      end
+
+      def set_failure(message)
+        @success = false
+        @error = message
+      end
+
+      # override in subclasses
+      def parse_response(_body)
+        # default no-op
+      end
+
+      # must override
+      def build_command
+        raise NotImplementedError, 'Subclasses must implement build_command'
+      end
+    end
+  end
+end

data/lib/vertexcache/command/command_type.rb

@@ -0,0 +1,29 @@
+# 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 Command
+    module CommandType
+      PING = 'PING'
+      SET  = 'SET'
+      DEL  = 'DEL'
+      IDX1 = 'IDX1'
+      IDX2 = 'IDX2'
+
+      ALL = [PING, SET, DEL, IDX1, IDX2].freeze
+    end
+  end
+end