volcano-sdk 0.5.2

data/lib/volcano/lock_session.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'English'
+
+module Volcano
+  # Owns renewal and cleanup for one block-scoped lock lease.
+  class LockSession
+    def initialize(locks, key, guard, renewer, delay)
+      @locks = locks
+      @key = key
+      @guard = guard
+      @renewer = renewer
+      @delay = delay
+      @renewer_started = false
+    end
+
+    def run
+      prepare
+      start
+      yield @guard
+    ensure
+      cleanup($ERROR_INFO.nil?)
+    end
+
+    private
+
+    def prepare
+      return unless @guard.renewal_delay(@delay).zero?
+
+      started_at = LockLeaseClock.capture
+      lease = @locks.renew(@key, @guard.lease, ttl: @guard.ttl)
+      replaced = @guard.replace_lease(lease, started_at: started_at)
+      return if replaced && @guard.renewal_delay(@delay).positive?
+
+      failure = Timeout::Error.new(LockGuard::UNSAFE_RENEWAL_MESSAGE)
+      @guard.mark_lost(failure)
+      raise failure
+    end
+
+    def start
+      @guard.start_expiry_watch
+      @renewer.start
+      @renewer_started = true
+    end
+
+    def cleanup(completed)
+      failure = nil
+      @guard.stop_expiry_watch
+      failure = @guard.failure
+      @renewer.stop if @renewer_started
+    ensure
+      finish(completed, failure)
+    end
+
+    def finish(completed, failure)
+      release_error = release_safely
+      return unless completed
+
+      raise failure if failure
+      raise release_error if release_error
+    end
+
+    def release_safely
+      @locks.release(@key, @guard.lease)
+      nil
+    rescue StandardError => e
+      e
+    end
+  end
+end

data/lib/volcano/locks.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Volcano
+  # Acquires and releases project-scoped distributed locks.
+  class Locks
+    include LockAutoRenewal
+
+    def initialize(client, transport)
+      @client = client
+      @transport = transport
+    end
+
+    def get(key)
+      payload = Transport.body(get_response(key), 200)
+      LockState.new(
+        held: payload.fetch('held'),
+        expires_at: parse_time(payload['expires_at']),
+        fencing_token: payload['fencing_token']
+      )
+    end
+
+    def acquire(key, ttl:)
+      token = SecureRandom.uuid
+      payload = Transport.body(acquire_response(key, ttl, token), 201)
+      LockLease.new(
+        key: key,
+        token: token,
+        expires_at: parse_time(payload['expires_at']),
+        fencing_token: payload['fencing_token']
+      )
+    end
+
+    def renew(key, lease, ttl:)
+      payload = Transport.body(renew_response(key, lease, ttl), 200)
+      LockLease.new(
+        key: key,
+        token: lease.token,
+        expires_at: parse_time(payload['expires_at']),
+        fencing_token: payload['fencing_token']
+      )
+    end
+
+    def release(key, lease)
+      response = Transport.invoke do
+        @transport.release_project_lock(
+          authorization: @client.service_token,
+          key: key,
+          token: lease.token
+        )
+      end
+      Transport.body(response, 204)
+      nil
+    end
+
+    def force_release(key)
+      Transport.body(force_release_response(key), 204)
+      nil
+    end
+
+    private
+
+    def get_response(key)
+      Transport.invoke do
+        @transport.get_project_lock(
+          authorization: @client.service_token,
+          key: key
+        )
+      end
+    end
+
+    def force_release_response(key)
+      Transport.invoke do
+        @transport.force_release_project_lock(
+          authorization: @client.service_token,
+          key: key
+        )
+      end
+    end
+
+    def acquire_response(key, ttl, token)
+      Transport.invoke do
+        @transport.acquire_project_lock(
+          authorization: @client.service_token,
+          key: key,
+          ttl: ttl,
+          token: token
+        )
+      end
+    end
+
+    def renew_response(key, lease, ttl)
+      Transport.invoke do
+        @transport.renew_project_lock(
+          authorization: @client.service_token,
+          key: key,
+          ttl: ttl,
+          token: lease.token
+        )
+      end
+    end
+
+    def parse_time(value)
+      value.is_a?(String) ? Time.iso8601(value) : value
+    end
+  end
+end

data/lib/volcano/log_responses.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Captures immutable JSON for log requests and responses.
+  module ImmutableLogJSON
+    private
+
+    def immutable_json(value)
+      case value
+      when Hash then value.to_h { |key, item| [immutable_json(key), immutable_json(item)] }.freeze
+      when Array then value.map { |item| immutable_json(item) }.freeze
+      when Time, String then value.dup.freeze
+      else value
+      end
+    end
+  end
+  private_constant :ImmutableLogJSON
+
+  # Immutable page returned by a project log search.
+  LogSearchResponse = Data.define(:data, :limit, :has_more, :next_cursor) do
+    include ImmutableLogJSON
+
+    def initialize(data:, limit:, has_more:, next_cursor: nil)
+      super(
+        data: immutable_json(data), limit: limit, has_more: has_more,
+        next_cursor: next_cursor&.dup&.freeze
+      )
+    end
+  end
+
+  # Immutable bucketed project log activity.
+  LogActivityResponse = Data.define(:data, :total) do
+    include ImmutableLogJSON
+
+    def initialize(data:, total:)
+      super(data: immutable_json(data), total: total)
+    end
+  end
+end

data/lib/volcano/logs.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Searches retained project logs and activity.
+  class Logs
+    include ImmutableLogJSON
+
+    def initialize(client, transport)
+      @client = client
+      @transport = transport
+    end
+
+    def search(project_id, request)
+      project_id, request = log_request(project_id, request)
+      response = @client.session_request do |token|
+        Transport.invoke do
+          @transport.search_project_logs(
+            authorization: token,
+            project_id: project_id,
+            request: request
+          )
+        end
+      end
+      search_response(Transport.body(response, 200))
+    end
+
+    def activity(project_id, request)
+      project_id, request = log_request(project_id, request)
+      response = @client.session_request do |token|
+        Transport.invoke do
+          @transport.get_project_log_activity(
+            authorization: token,
+            project_id: project_id,
+            request: request
+          )
+        end
+      end
+      activity_response(Transport.body(response, 200))
+    end
+
+    private
+
+    def log_request(project_id, request)
+      unless project_id.is_a?(String) && !project_id.strip.empty?
+        raise ArgumentError, 'project_id must be a non-empty String'
+      end
+      raise TypeError, 'Log request must be a Hash' unless request.is_a?(Hash)
+
+      [project_id.dup.freeze, immutable_json(request)]
+    end
+
+    def search_response(body)
+      data = response_data(body)
+      limit = body['limit']
+      has_more = body['has_more']
+      next_cursor = body['next_cursor']
+      unless limit.is_a?(Integer) && [true, false].include?(has_more) &&
+             (next_cursor.nil? || next_cursor.is_a?(String))
+        raise TypeError, 'Expected a complete log response'
+      end
+
+      LogSearchResponse.new(
+        data: data, limit: limit, has_more: has_more, next_cursor: next_cursor
+      )
+    end
+
+    def activity_response(body)
+      data = response_data(body)
+      total = body['total']
+      raise TypeError, 'Expected a complete log response' unless total.is_a?(Integer)
+
+      LogActivityResponse.new(data: data, total: total)
+    end
+
+    def response_data(body)
+      data = body['data'] if body.is_a?(Hash)
+      raise TypeError, 'Expected a complete log response' unless data.is_a?(Array) && data.all?(Hash)
+
+      data
+    end
+  end
+end

data/lib/volcano/models.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Volcano
+  Session = Data.define(:access_token, :refresh_token, :user_id)
+  AUTH_SESSION_ATTRIBUTES = %i[
+    id user_id provider expires_at is_active is_current user_agent ip_address last_ip_address
+    last_activity_at session_started_at created_at updated_at
+  ].freeze
+  private_constant :AUTH_SESSION_ATTRIBUTES
+
+  AuthSession = Data.define(*AUTH_SESSION_ATTRIBUTES) do
+    def initialize(**attributes)
+      unknown = attributes.keys - AUTH_SESSION_ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      missing = AUTH_SESSION_ATTRIBUTES.first(6) - attributes.keys
+      raise ArgumentError, "missing keywords: #{missing.join(', ')}" unless missing.empty?
+
+      values = AUTH_SESSION_ATTRIBUTES.to_h do |name|
+        [name, freeze_session_value(attributes[name])]
+      end
+      super(**values)
+    end
+
+    private
+
+    def freeze_session_value(value)
+      value.frozen? ? value : value.dup.freeze
+    end
+  end
+
+  SessionPage = Data.define(:sessions, :total, :page, :limit, :total_pages) do
+    def initialize(sessions:, total:, page:, limit:, total_pages:)
+      super(sessions: sessions.to_a.dup.freeze, total: total, page: page, limit: limit,
+            total_pages: total_pages)
+    end
+  end
+  LinkedOAuthProvider = Data.define(:provider, :linked_at, :updated_at) do
+    def initialize(provider:, linked_at:, updated_at:)
+      super(
+        provider: immutable_value(provider),
+        linked_at: immutable_value(linked_at),
+        updated_at: immutable_value(updated_at)
+      )
+    end
+
+    private
+
+    def immutable_value(value)
+      value.frozen? ? value : value.dup.freeze
+    end
+  end
+  OAuthProviderTokenStatus = Data.define(:message, :provider, :expires_in) do
+    def initialize(message:, provider:, expires_in:)
+      values = [message, provider]
+      valid = values.all? { |value| value.is_a?(String) && !value.strip.empty? }
+      raise TypeError, 'Expected complete OAuth provider token status' unless valid && expires_in.is_a?(Integer)
+
+      super(message: message.dup.freeze, provider: provider.dup.freeze, expires_in: expires_in)
+    end
+  end
+  EmailChangeResult = Data.define(:message, :new_email)
+  USER_OPTIONAL_ATTRIBUTES = %i[
+    project_id email_confirmed user_metadata app_metadata avatar_url banned_until
+    last_sign_in_at created_at updated_at
+  ].freeze
+  private_constant :USER_OPTIONAL_ATTRIBUTES
+
+  User = Data.define(
+    :id, :project_id, :email, :email_confirmed, :user_metadata, :app_metadata,
+    :avatar_url, :status, :banned_until, :last_sign_in_at, :created_at, :updated_at
+  ) do
+    def initialize(id:, email:, status:, **attributes)
+      validate_optional_attributes(attributes)
+      super(
+        id: freeze_value(id),
+        email: freeze_value(email),
+        status: freeze_value(status),
+        **USER_OPTIONAL_ATTRIBUTES.to_h { |name| [name, freeze_value(attributes[name])] }
+      )
+    end
+
+    private
+
+    def validate_optional_attributes(attributes)
+      unknown = attributes.keys - USER_OPTIONAL_ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+    end
+
+    def freeze_value(value)
+      case value
+      when Hash then value.to_h { |key, item| [freeze_value(key), freeze_value(item)] }.freeze
+      when Array then value.map { |item| freeze_value(item) }.freeze
+      when String then value.dup.freeze
+      else value.frozen? ? value : value.dup.freeze
+      end
+    end
+  end
+  LockLease = Data.define(:key, :token, :expires_at, :fencing_token) do
+    def initialize(key:, token:, expires_at:, fencing_token:)
+      super(
+        key: key.dup.freeze,
+        token: token.dup.freeze,
+        expires_at: expires_at&.dup&.freeze,
+        fencing_token: fencing_token
+      )
+    end
+  end
+  LockState = Data.define(:held, :expires_at, :fencing_token) do
+    def initialize(held:, expires_at:, fencing_token:)
+      immutable_expiry = expires_at&.then { |value| value.frozen? ? value : value.dup.freeze }
+      super(held: held, expires_at: immutable_expiry, fencing_token: fencing_token)
+    end
+  end
+end

data/lib/volcano/realtime/blocking_call.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Runs one blocking operation off the Async reactor and returns its result.
+    module BlockingCall
+      Result = Data.define(:value, :error)
+      private_constant :Result
+
+      module_function
+
+      def call(&operation)
+        results = ::Queue.new
+        worker = Thread.new { execute(results, operation) }
+        worker.report_on_exception = false
+        result = results.pop
+        worker.join
+        raise result.error if result.error
+
+        result.value
+      end
+
+      def execute(results, operation)
+        results << Result.new(value: operation.call, error: nil)
+      rescue StandardError => e
+        results << Result.new(value: nil, error: e)
+      end
+      private_class_method :execute
+    end
+    private_constant :BlockingCall
+  end
+end

data/lib/volcano/realtime/broadcast_delivery.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Delivers broadcasts only while their subscription generation is current.
+    module BroadcastDelivery
+      PublicationContext = Data.define(:protocol, :publication, :generation, :recovered) do
+        def initialize(protocol:, publication:, generation:, recovered:)
+          super(protocol:, publication: Immutable.call(publication), generation:, recovered:)
+        end
+      end
+      private_constant :PublicationContext
+
+      private
+
+      def deliver_broadcast(event, data, context)
+        return reject_broadcast(context) unless broadcast_message?(event, data)
+
+        emit(
+          'message', Immutable.call(data),
+          before_delivery: -> { complete_broadcast(context) }
+        )
+      end
+
+      def broadcast_message?(event, data)
+        event == 'message' && data.is_a?(Hash) && @callbacks['message'].any?
+      end
+
+      def publication_context(protocol, publication, generation, recovered)
+        PublicationContext.new(protocol:, publication:, generation:, recovered:)
+      end
+
+      def reject_broadcast(context)
+        with_current_publication(context) do
+          context.protocol.__send__(:drop_publication, @name, context.publication)
+        end
+      end
+
+      def complete_broadcast(context)
+        with_current_publication(context) do
+          context.protocol.__send__(:complete_publication, @name, context.publication)
+        end
+      end
+
+      def with_current_publication(context)
+        with_lifecycle_lock do
+          next false unless context.generation == @publication_generation
+
+          yield
+          true
+        end
+      end
+
+      def clear_broadcast_recovery_state
+        return unless broadcast? && @publication_protocol
+
+        @publication_protocol.__send__(:delete_recovery_state, @name)
+        @publication_protocol = nil
+      end
+    end
+    private_constant :BroadcastDelivery
+  end
+end

data/lib/volcano/realtime/channel_callbacks.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Registers channel callbacks and connects them to protocol pushes.
+    module ChannelCallbacks
+      def on(event, callback = nil, &block)
+        raise ArgumentError, "unsupported realtime event: #{event}" unless allowed_event?(event)
+
+        @callbacks[event] << (callback || block || raise(ArgumentError, 'callback or block is required'))
+        self
+      end
+
+      private
+
+      def initialize_callback_dispatch
+        @callbacks = Hash.new { |hash, key| hash[key] = [] }
+        @publication_handler = @callback_lock = @callback_task = nil
+        @publication_protocol = nil
+        @publication_generation = 0
+        @deferred_callback_deliveries = []
+      end
+
+      def allowed_event?(event)
+        event == 'message' || (presence? && %w[join leave presence_sync].include?(event)) ||
+          (postgres? && PostgresChanges::EVENTS.include?(event))
+      end
+
+      def register_handlers(protocol, epoch)
+        register_publication_handler(protocol)
+        register_presence_handler(protocol, epoch)
+      end
+
+      def register_publication_handler(protocol)
+        return if @handler_registered
+
+        generation = @publication_generation
+        @publication_protocol = protocol if broadcast?
+        @publication_handler = protocol.on_publication(
+          @name, on_rejection: publication_rejection(protocol, generation)
+        ) do |event, data, publication, recovered:|
+          next deliver_publication(event, data) unless broadcast?
+
+          context = publication_context(protocol, publication, generation, recovered)
+          deliver_broadcast(event, data, context)
+        end
+        @handler_registered = true
+      end
+
+      def publication_rejection(protocol, generation)
+        return unless broadcast?
+
+        lambda do |publication|
+          reject_broadcast(publication_context(protocol, publication, generation, false))
+        end
+      end
+
+      def deliver_publication(event, data)
+        if postgres?
+          dispatch_postgres_change(data)
+        elsif event == 'message'
+          emit('message', data)
+        end
+      end
+
+      def emit(event, data, before_delivery: nil)
+        callbacks = @callbacks[event].dup
+        return if callbacks.empty?
+
+        delivery = [event, data, callbacks, before_delivery]
+        return defer_callback_delivery(delivery) if callback_dispatching?
+
+        callback_lock.acquire { dispatch_callback_delivery(delivery) }
+        nil
+      end
+
+      def callback_dispatching?
+        @callback_task.equal?(Async::Task.current)
+      end
+
+      def defer_callback_delivery(delivery)
+        @deferred_callback_deliveries << delivery
+        nil
+      end
+
+      def dispatch_callback_delivery(delivery)
+        @callback_task = Async::Task.current
+        @deferred_callback_deliveries << delivery
+        dispatch_deferred_callbacks until @deferred_callback_deliveries.empty?
+      ensure
+        @callback_task = nil
+      end
+
+      def dispatch_deferred_callbacks
+        event, data, callbacks, before_delivery = @deferred_callback_deliveries.shift
+        return if before_delivery && !before_delivery.call
+
+        dispatch_callbacks(event, data, callbacks)
+      end
+
+      def dispatch_callbacks(event, data, callbacks)
+        callbacks.each do |callback|
+          next unless @callbacks[event].include?(callback)
+
+          callback.call(data)
+        rescue StandardError
+          next
+        end
+      end
+
+      def detach_publication_handler(protocol)
+        if @publication_handler
+          protocol.off_publication(@name, @publication_handler)
+          @publication_generation += 1 if broadcast?
+        end
+        detach_presence_handler(protocol)
+        @publication_handler = nil
+      end
+
+      def callback_lock
+        require 'async/semaphore'
+        @callback_lock ||= Async::Semaphore.new(1)
+      end
+    end
+    private_constant :ChannelCallbacks
+  end
+end