volcano-sdk 0.5.2

data/lib/volcano/generated_transport_support.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Internal transport implementation assembled across support modules.
+  class GeneratedTransport
+    # Resolves generated model constants across the private namespace boundary.
+    module ModelDeserialization
+      def _deserialize(type, value)
+        super
+      rescue NameError => e
+        raise unless e.name == :Generated && e.message.include?('private constant Volcano::Generated')
+
+        klass = Generated.const_get(type)
+        if klass.respond_to?(:openapi_any_of) || klass.respond_to?(:openapi_one_of)
+          klass.build(value)
+        else
+          klass.build_from_hash(value)
+        end
+      end
+    end
+    private_constant :ModelDeserialization
+
+    Generated::ApiModelBase.singleton_class.prepend(ModelDeserialization)
+
+    # Corrects generated content negotiation and private model lookup.
+    class ApiClient < Generated::ApiClient
+      def build_request(http_method, path, options = {})
+        request = super
+        request.options[:followlocation] = options.fetch(:follow_location, true)
+        request.options[:params_encoding] = options.fetch(:params_encoding, request.options[:params_encoding])
+        request
+      end
+
+      def select_header_content_type(content_types)
+        if content_types.include?('multipart/form-data') && content_types.include?('application/json')
+          return 'multipart/form-data'
+        end
+
+        super
+      end
+
+      def convert_to_type(data, return_type)
+        super
+      rescue NameError => e
+        raise unless e.name == :Generated && e.message.include?('private constant Volcano::Generated')
+
+        klass = Generated.const_get(return_type)
+        klass.respond_to?(:openapi_one_of) ? klass.build(data) : klass.build_from_hash(data)
+      end
+    end
+
+    # Captures a generated request URL without performing network I/O.
+    class AuthorizationURLApiClient < ApiClient
+      def call_api(http_method, path, options = {})
+        [build_request(http_method, path, options).url, 0, {}]
+      end
+    end
+    private_constant :AuthorizationURLApiClient
+
+    # Implements storage endpoints omitted by the generated API surface.
+    class StorageApi < Generated::StorageObjectsApi
+      include UploadSessionStorageApi
+
+      UPLOAD_OPTIONS = {
+        operation: :'StorageObjectsApi.upload_storage_object',
+        header_params: { 'Accept' => 'application/json', 'Content-Type' => 'multipart/form-data' }.freeze,
+        auth_names: %w[ServiceRoleKey AuthUserAccessToken AnonKey].freeze,
+        return_type: 'StorageObject'
+      }.freeze
+      DOWNLOAD_OPTIONS = {
+        operation: :'StorageObjectsApi.download_storage_object',
+        header_params: { 'Accept' => 'application/octet-stream, application/json' }.freeze,
+        auth_names: %w[ServiceRoleKey AuthUserAccessToken AnonKey].freeze,
+        return_type: 'File'
+      }.freeze
+      DELETE_OPTIONS = {
+        operation: :'StorageObjectsApi.delete_storage_object',
+        header_params: { 'Accept' => 'application/json' }.freeze,
+        auth_names: %w[ServiceRoleKey AuthUserAccessToken].freeze
+      }.freeze
+      VISIBILITY_OPTIONS = {
+        operation: :'StorageObjectsApi.update_storage_object_visibility',
+        header_params: { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }.freeze,
+        auth_names: %w[ServiceRoleKey AuthUserAccessToken].freeze,
+        return_type: 'StorageObject'
+      }.freeze
+
+      def upload_storage_object_with_http_info(bucket_name, path, file, opts = {})
+        if opts[:content_type]
+          # Ethon accepts [filename, MIME type, local path] with encoding disabled.
+          file = [File.basename(file.path), opts[:content_type], File.expand_path(file.path)]
+          opts = opts.merge(params_encoding: :none)
+        end
+        options = opts.merge(UPLOAD_OPTIONS).merge(form_params: { 'file' => file })
+        call_storage_api(:POST, bucket_name, path, options)
+      end
+
+      def download_storage_object_with_http_info(bucket_name, path, opts = {})
+        header_params = DOWNLOAD_OPTIONS.fetch(:header_params).merge(opts[:header_params] || {})
+        header_params['Range'] = opts[:range] unless opts[:range].nil?
+        options = opts.merge(DOWNLOAD_OPTIONS, header_params: header_params)
+
+        call_storage_api(:GET, bucket_name, path, options)
+      end
+
+      def delete_storage_object_with_http_info(bucket_name, path, opts = {})
+        call_storage_api(:DELETE, bucket_name, path, opts.merge(DELETE_OPTIONS))
+      end
+
+      def update_storage_object_visibility_with_http_info(bucket_name, path, request, opts = {})
+        options = opts.merge(VISIBILITY_OPTIONS).merge(body: api_client.object_to_http_body(request))
+        call_storage_api(:PATCH, bucket_name, path, options, suffix: '/visibility')
+      end
+
+      private
+
+      def call_storage_api(method, bucket_name, path, options, suffix: '')
+        raise ArgumentError, 'bucket_name is required' if bucket_name.nil?
+        raise ArgumentError, 'path is required' if path.nil?
+
+        bucket = CGI.escapeURIComponent(bucket_name.to_s)
+        object_path = CGI.escapeURIComponent(path.to_s).gsub('%2F', '/')
+        api_client.call_api(method, "/storage/#{bucket}/#{object_path}#{suffix}", options)
+      end
+    end
+
+    # Normalizes values returned by the generated client.
+    module ValueNormalization
+      private
+
+      def parse_body(value)
+        return {} if value.nil? || value.empty?
+
+        JSON.parse(value)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def plain_value(value)
+        value = value.to_hash if value.respond_to?(:to_hash)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_s, plain_value(item)] }
+        when Array then value.map { |item| plain_value(item) }
+        else value
+        end
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_sym, deep_symbolize(item)] }
+        when Array then value.map { |item| deep_symbolize(item) }
+        else value
+        end
+      end
+
+      def binary_data(value)
+        return value.to_s.b unless value.respond_to?(:read)
+
+        prepare_stream(value)
+        value.read.b
+      ensure
+        value.close! if value.respond_to?(:close!)
+      end
+
+      def prepare_stream(value)
+        value.open if value.respond_to?(:closed?) && value.closed? && value.respond_to?(:open)
+        value.binmode if value.respond_to?(:binmode)
+        value.rewind if value.respond_to?(:rewind)
+      end
+    end
+
+    # Builds generated API wrappers with consistent authentication and timeouts.
+    module ApiFactory
+      private
+
+      def build_apis(authorization)
+        api_client = ApiClient.new(generated_configuration(authorization))
+        generated_apis(api_client)
+      end
+
+      def generated_configuration(authorization)
+        uri = URI(@api_url)
+        Generated::Configuration.new.tap do |configuration|
+          configuration.scheme = uri.scheme
+          configuration.host = host_with_port(uri)
+          configuration.base_path = uri.path == '/' ? '' : uri.path
+          configuration.ignore_operation_servers = true
+          configuration.access_token = authorization
+          configuration.timeout = timeout_milliseconds
+        end
+      end
+
+      def timeout_milliseconds
+        (@timeout * 1_000).round
+      end
+
+      def generated_apis(api_client)
+        GeneratedApis.new(
+          authentication: Generated::AuthenticationApi.new(api_client),
+          oauth: Generated::OAuthAuthenticationApi.new(api_client),
+          database: Generated::DatabaseQueriesApi.new(api_client),
+          storage: StorageApi.new(api_client),
+          locks: Generated::LocksApi.new(api_client),
+          functions: Generated::FunctionsApi.new(api_client),
+          logs: Generated::LogsApi.new(api_client)
+        )
+      end
+
+      def oauth_authorization_api
+        api_client = AuthorizationURLApiClient.new(generated_configuration(nil))
+        Generated::OAuthAuthenticationApi.new(api_client)
+      end
+
+      def host_with_port(uri)
+        return uri.host if uri.port == uri.default_port
+
+        "#{uri.host}:#{uri.port}"
+      end
+    end
+  end
+end

data/lib/volcano/generated_transport_upload_session_api.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Corrects generated HTTP operations for resumable storage uploads.
+  module UploadSessionStorageApi
+    CREATE_OPTIONS = {
+      operation: :'StorageObjectsApi.upload_storage_object',
+      header_params: { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }.freeze,
+      auth_names: %w[ServiceRoleKey AuthUserAccessToken AnonKey].freeze,
+      return_type: 'CreateUploadSessionResponse'
+    }.freeze
+    UPLOAD_PART_OPTIONS = {
+      operation: :'StorageObjectsApi.upload_part',
+      header_params: { 'Accept' => 'application/json', 'Content-Type' => 'application/octet-stream' }.freeze,
+      auth_names: %w[ServiceRoleKey AuthUserAccessToken AnonKey].freeze,
+      return_type: 'UploadSessionPart'
+    }.freeze
+    COMPLETE_OPTIONS = {
+      operation: :'StorageObjectsApi.upload_storage_object',
+      header_params: { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }.freeze,
+      auth_names: %w[ServiceRoleKey AuthUserAccessToken AnonKey].freeze,
+      return_type: 'CompleteUploadSessionResponse'
+    }.freeze
+    STATUS_OPTIONS = {
+      operation: :'StorageObjectsApi.download_storage_object',
+      header_params: { 'Accept' => 'application/json' }.freeze,
+      auth_names: %w[ServiceRoleKey AuthUserAccessToken AnonKey].freeze,
+      return_type: 'UploadSessionStatusResponse'
+    }.freeze
+    ABORT_OPTIONS = {
+      operation: :'StorageObjectsApi.delete_storage_object',
+      header_params: { 'Accept' => 'application/json' }.freeze,
+      auth_names: %w[ServiceRoleKey AuthUserAccessToken].freeze
+    }.freeze
+
+    def create_upload_session_with_http_info(bucket_name, path, request)
+      options = CREATE_OPTIONS.merge(body: api_client.object_to_http_body(request))
+      call_storage_api(:POST, bucket_name, path, options)
+    end
+
+    def upload_part_with_http_info(bucket_name, path, session_id, part_number, data)
+      headers = UPLOAD_PART_OPTIONS.fetch(:header_params).merge(
+        'X-Upload-Session' => session_id, 'X-Part-Number' => part_number.to_s
+      )
+      call_storage_api(
+        :PUT, bucket_name, path, UPLOAD_PART_OPTIONS.merge(header_params: headers, body: data)
+      )
+    end
+
+    def complete_upload_session_with_http_info(bucket_name, path, session_id)
+      headers = COMPLETE_OPTIONS.fetch(:header_params).merge(
+        'X-Upload-Session' => session_id, 'X-Upload-Complete' => 'true'
+      )
+      options = COMPLETE_OPTIONS.merge(header_params: headers, body: JSON.generate({}))
+      call_storage_api(:POST, bucket_name, path, options)
+    end
+
+    def get_upload_session_with_http_info(bucket_name, path, session_id)
+      headers = STATUS_OPTIONS.fetch(:header_params).merge('X-Upload-Session' => session_id)
+      call_storage_api(:GET, bucket_name, path, STATUS_OPTIONS.merge(header_params: headers))
+    end
+
+    def abort_upload_session_with_http_info(bucket_name, path, session_id)
+      headers = ABORT_OPTIONS.fetch(:header_params).merge('X-Upload-Session' => session_id)
+      call_storage_api(:DELETE, bucket_name, path, ABORT_OPTIONS.merge(header_params: headers))
+    end
+  end
+  private_constant :UploadSessionStorageApi
+end

data/lib/volcano/generated_transport_upload_sessions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Resumable storage operations for the internal generated transport.
+  class GeneratedTransport
+    def create_upload_session(authorization:, bucket_name:, request:)
+      invoke do
+        attributes = {
+          object_path: request.path,
+          content_type: request.content_type,
+          total_size: request.total_size,
+          part_size: request.part_size
+        }.compact
+        generated_request = Generated::CreateUploadSessionRequest.new(attributes)
+        apis = @api_factory.call(authorization)
+        data, status, headers = apis.storage.create_upload_session_with_http_info(
+          bucket_name, request.path, generated_request
+        )
+        response(data, status, headers)
+      end
+    end
+
+    def upload_part(authorization:, bucket_name:, request:)
+      invoke do
+        apis = @api_factory.call(authorization)
+        data, status, headers = apis.storage.upload_part_with_http_info(
+          bucket_name,
+          request.path,
+          request.session_id,
+          request.part_number,
+          request.data
+        )
+        response(data, status, headers)
+      end
+    end
+
+    def complete_upload_session(authorization:, bucket_name:, request:)
+      invoke do
+        apis = @api_factory.call(authorization)
+        data, status, headers = apis.storage.complete_upload_session_with_http_info(
+          bucket_name, request.path, request.session_id
+        )
+        response(data, status, headers)
+      end
+    end
+
+    def get_upload_session(authorization:, bucket_name:, request:)
+      invoke do
+        apis = @api_factory.call(authorization)
+        data, status, headers = apis.storage.get_upload_session_with_http_info(
+          bucket_name, request.path, request.session_id
+        )
+        response(data, status, headers)
+      end
+    end
+
+    def abort_upload_session(authorization:, bucket_name:, request:)
+      invoke do
+        apis = @api_factory.call(authorization)
+        data, status, headers = apis.storage.abort_upload_session_with_http_info(
+          bucket_name, request.path, request.session_id
+        )
+        response(data, status, headers)
+      end
+    end
+  end
+end

data/lib/volcano/lock_auto_renewal.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Adds block-scoped automatic renewal to the lock facade.
+  module LockAutoRenewal
+    MIN_LOCK_TTL_SECONDS = 5
+    MAX_LOCK_TTL_SECONDS = 7_776_000
+    MAX_RENEWAL_DELAY_SECONDS = 60.0
+    RENEWAL_SAFETY_MARGIN_SECONDS = 1.0
+    RENEWAL_REQUEST_BUDGET_SECONDS = 1.0
+    RENEWER_SHUTDOWN_TIMEOUT_SECONDS = 1.0
+
+    def with_lock(key, ttl:, &)
+      validate_ttl(ttl)
+      started_at = LockLeaseClock.capture
+      guard = LockGuard.new(acquire(key, ttl: ttl), ttl: ttl, started_at: started_at)
+      owned_key = guard.lease.key
+      renewer = lock_renewer(owned_key, guard, ttl)
+      LockSession.new(self, owned_key, guard, renewer, method(:renewal_delay)).run(&)
+    end
+
+    private
+
+    def lock_renewer(key, guard, ttl)
+      config = LockRenewer::Config.new(
+        ttl: ttl, delay: method(:renewal_delay),
+        shutdown_timeout: RENEWER_SHUTDOWN_TIMEOUT_SECONDS
+      )
+      LockRenewer.new(self, key, guard, config)
+    end
+
+    def renewal_delay(ttl, remaining: nil)
+      delay = [ttl / 3.0, MAX_RENEWAL_DELAY_SECONDS].min
+      latest = latest_renewal_delay(remaining)
+      delay = [delay, latest].min if latest
+      jittered = [0.0, delay * (0.9 + (rand * 0.2))].max
+      latest ? [jittered, latest].min : jittered
+    end
+
+    def latest_renewal_delay(remaining)
+      return unless remaining
+
+      [0.0, remaining - RENEWAL_SAFETY_MARGIN_SECONDS - RENEWAL_REQUEST_BUDGET_SECONDS].max
+    end
+
+    def validate_ttl(ttl)
+      valid = ttl.is_a?(Integer) && ttl.between?(MIN_LOCK_TTL_SECONDS, MAX_LOCK_TTL_SECONDS)
+      raise ArgumentError, 'ttl must be an integer between 5 seconds and 90 days' unless valid
+    end
+  end
+end

data/lib/volcano/lock_guard.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Volcano
+  # Exposes the latest lease and reports asynchronous lease loss.
+  class LockGuard
+    EXPIRY_MESSAGE = 'lock lease expired before renewal completed'
+    MAX_EXPIRY_POLL_SECONDS = 1.0
+    UNSAFE_RENEWAL_MESSAGE = 'lock renewal returned no safe lease window'
+
+    attr_reader :ttl
+
+    def initialize(lease, ttl:, started_at:)
+      @lease = lease
+      @ttl = ttl
+      @lease_clock = LockLeaseClock.new(ttl: ttl, started_at: started_at)
+      @mutex = Mutex.new
+      @changed = ConditionVariable.new
+      @failure = nil
+      @expiry_stopped = false
+      @expiry_thread = nil
+    end
+
+    def lease = @mutex.synchronize { @lease }
+
+    def lost?
+      @mutex.synchronize do
+        record_expiry_if_needed
+        !@failure.nil?
+      end
+    end
+
+    def wait_lost(timeout: nil) = @mutex.synchronize { wait_for_failure?(wait_deadline(timeout)) }
+
+    def replace_lease(lease, started_at:)
+      @mutex.synchronize do
+        return false if @failure
+
+        @lease = lease
+        @lease_clock.reset(started_at)
+        @changed.broadcast
+        true
+      end
+    end
+
+    def mark_lost(failure)
+      @mutex.synchronize do
+        @failure ||= failure
+        @changed.broadcast
+      end
+    end
+
+    def failure
+      @mutex.synchronize do
+        record_expiry_if_needed
+        @failure
+      end
+    end
+
+    def renewal_delay(delay) = @mutex.synchronize { delay.call(@ttl, remaining: remaining_time) }
+
+    def start_expiry_watch
+      @mutex.synchronize { @expiry_stopped = false }
+      @expiry_thread = Thread.new { expiry_loop }
+    end
+
+    def stop_expiry_watch
+      @mutex.synchronize do
+        record_expiry_if_needed
+        @expiry_stopped = true
+        @changed.broadcast
+      end
+      @expiry_thread&.join
+    end
+
+    private
+
+    def wait_for_failure?(deadline)
+      loop do
+        record_expiry_if_needed
+        return true if @failure
+
+        wait = wait_duration(deadline)
+        return false unless wait
+
+        @changed.wait(@mutex, wait)
+      end
+    end
+
+    def wait_duration(deadline)
+      return [expiry_delay, MAX_EXPIRY_POLL_SECONDS].min unless deadline
+
+      caller_remaining = deadline - @lease_clock.monotonic_now
+      return if caller_remaining <= 0
+
+      [expiry_delay, caller_remaining, MAX_EXPIRY_POLL_SECONDS].min
+    end
+
+    def expiry_loop
+      loop do
+        state = @mutex.synchronize { expiry_step }
+        break if state == :finished
+      end
+    end
+
+    def expiry_step
+      return :finished if @expiry_stopped
+
+      delay = expiry_delay
+      return record_expiry if delay <= 0
+
+      @changed.wait(@mutex, [delay, MAX_EXPIRY_POLL_SECONDS].min)
+      :waiting
+    end
+
+    def expiry_delay = remaining_time
+
+    def record_expiry
+      @failure ||= Timeout::Error.new(EXPIRY_MESSAGE)
+      @changed.broadcast
+      :finished
+    end
+
+    def record_expiry_if_needed
+      record_expiry if !@failure && remaining_time <= 0
+    end
+
+    def remaining_time = @lease_clock.remaining
+
+    def wait_deadline(timeout)
+      timeout && (@lease_clock.monotonic_now + timeout)
+    end
+  end
+end

data/lib/volcano/lock_lease_clock.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Tracks lease age across wall-clock changes and host suspension.
+  class LockLeaseClock
+    MAX_LEASE_LIFETIME_SECONDS = 7_776_000
+    SUSPEND_AWARE = Process.const_defined?(:CLOCK_BOOTTIME)
+    CLOCK_ID = SUSPEND_AWARE ? Process.const_get(:CLOCK_BOOTTIME) : Process::CLOCK_MONOTONIC
+    Timestamp = Data.define(:monotonic, :wall)
+
+    def self.now = Process.clock_gettime(CLOCK_ID)
+    def self.capture = Timestamp.new(monotonic: now, wall: Time.now)
+    def self.suspend_aware? = SUSPEND_AWARE
+
+    def initialize(ttl:, started_at:)
+      @ttl = ttl
+      @absolute_deadline = started_at.monotonic + MAX_LEASE_LIFETIME_SECONDS
+      @absolute_wall_deadline = started_at.wall + MAX_LEASE_LIFETIME_SECONDS
+      reset(started_at)
+    end
+
+    def reset(started_at)
+      @deadline = [started_at.monotonic + @ttl, @absolute_deadline].min
+      @wall_deadline = [started_at.wall + @ttl, @absolute_wall_deadline].min
+    end
+
+    def remaining
+      monotonic_remaining = @deadline - monotonic_now
+      remaining = if self.class.suspend_aware?
+                    monotonic_remaining
+                  else
+                    [monotonic_remaining, @wall_deadline - Time.now].min
+                  end
+      remaining.clamp(0.0, Float::INFINITY)
+    end
+
+    def monotonic_now = self.class.now
+  end
+end

data/lib/volcano/lock_renewer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Renews one guarded lease until its block exits or ownership is lost.
+  class LockRenewer
+    Config = Data.define(:ttl, :delay, :shutdown_timeout)
+
+    def initialize(locks, key, guard, config)
+      @locks = locks
+      @key = key
+      @guard = guard
+      @config = config
+      @mutex = Mutex.new
+      @stopped = ConditionVariable.new
+      @stop = false
+      @thread = nil
+    end
+
+    def start
+      @thread = Thread.new { renewal_loop }
+    end
+
+    def stop
+      request_stop
+      return unless @thread
+
+      # Renew requires current token ownership, so a late request cannot resurrect a released lease.
+      @thread.join(@config.shutdown_timeout)
+    end
+
+    private
+
+    def renewal_loop
+      loop do
+        return if @guard.lost?
+        return if wait_to_renew
+        return if @guard.lost?
+
+        renew
+      end
+    end
+
+    def wait_to_renew
+      seconds = @guard.renewal_delay(@config.delay)
+      @mutex.synchronize do
+        @stopped.wait(@mutex, seconds) unless @stop
+        @stop
+      end
+    end
+
+    def renew
+      started_at = LockLeaseClock.capture
+      lease = @locks.renew(@key, @guard.lease, ttl: @config.ttl)
+      replaced = @guard.replace_lease(lease, started_at: started_at)
+      return if replaced && renewal_safe?
+
+      @guard.mark_lost(Timeout::Error.new(LockGuard::UNSAFE_RENEWAL_MESSAGE))
+    rescue StandardError => e
+      @guard.mark_lost(e)
+    end
+
+    def renewal_safe?
+      @guard.renewal_delay(@config.delay).positive?
+    end
+
+    def request_stop
+      @mutex.synchronize do
+        @stop = true
+        @stopped.broadcast
+      end
+    end
+  end
+end