volcano-sdk 0.5.2

data/lib/volcano/auth_refresh.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Refreshes only the session captured by the initiating operation.
+  class Auth
+    def refresh_session
+      binding = @client.capture_session_binding
+      raise Error::AuthenticationError, 'No active session' unless binding.last
+
+      refresh_captured_session(binding)
+    end
+
+    def session_request
+      binding = @client.capture_session_binding
+      raise Error::AuthenticationError, 'No active session' unless binding.last
+
+      response = yield(binding.last.access_token)
+      return response unless response.status == 401
+
+      session = retry_session(binding)
+      return response unless session
+
+      token = owned_session_binding(binding).last.access_token
+      response = yield(token)
+      owned_session_binding(binding)
+      response
+    end
+
+    alias session_read session_request
+
+    private
+
+    def retry_session(binding)
+      refresh_captured_session(binding)
+    rescue Error::SessionChangedError
+      raise
+    rescue Error::VolcanoError
+      validate_read_failure(binding)
+      nil
+    end
+
+    def validate_read_failure(binding)
+      owned_session_binding(binding)
+    rescue Error::AuthenticationError
+      nil
+    end
+
+    def refresh_captured_session(binding)
+      refresh_with_notifications(binding)
+      owned_session_binding(binding).last
+    end
+
+    def refresh_with_notifications(binding)
+      notifications = []
+      @refresh_lock.synchronize do
+        active_generation, = owned_session_binding(binding)
+        perform_refresh(binding, notifications) if active_generation == binding.first
+      end
+    ensure
+      # Only the dispatcher owner drains, after refresh coordination is released.
+      notifications.each(&:call)
+    end
+
+    def owned_session_binding(binding)
+      active = @client.capture_session_binding
+      raise Error::AuthenticationError, 'No active session' if rejected_refresh?(binding, active)
+
+      generation, active_lineage, current = active
+      raise Error::SessionChangedError unless current && active_lineage == binding[1]
+
+      [generation, current]
+    end
+
+    def rejected_refresh?(binding, active)
+      generation, lineage, = binding
+      @rejected_refresh == [generation, lineage] &&
+        active == [generation + 1, lineage + 1, nil]
+    end
+
+    def perform_refresh(binding, notifications)
+      session = refreshed_session(binding, notifications)
+      stored = @client.store_session_if_current?(
+        session, binding.first, event: :token_refreshed, notifications: notifications
+      )
+      raise Error::SessionChangedError unless stored
+    end
+
+    def refreshed_session(binding, notifications)
+      owned_complete_session(build_session(refresh_payload(binding, notifications)))
+    rescue KeyError, TypeError, NoMethodError, ArgumentError => e
+      raise Error::TransportError, INCOMPLETE_SESSION, cause: e
+    end
+
+    def refresh_response(refresh_token)
+      Transport.invoke do
+        @transport.auth_refresh(
+          authorization: @client.anon_token,
+          refresh_token: refresh_token
+        )
+      end
+    end
+
+    def refresh_payload(binding, notifications)
+      Transport.body(refresh_response(binding.last.refresh_token), 200)
+    rescue Error::AuthenticationError
+      generation, lineage, = binding
+      cleared = @client.clear_session_if_current?(generation, notifications: notifications)
+      raise Error::SessionChangedError unless cleared
+
+      @rejected_refresh = [generation, lineage]
+      raise
+    rescue Error::VolcanoError
+      owned_session_binding(binding)
+      raise
+    end
+  end
+end

data/lib/volcano/auth_resend_confirmation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Enumeration-safe confirmation resend behavior for the auth facade.
+  class Auth
+    def resend_confirmation(email:)
+      Transport.body(resend_confirmation_response(email:), 200)
+      nil
+    end
+
+    private
+
+    def resend_confirmation_response(email:)
+      Transport.invoke do
+        @transport.auth_resend_confirmation(authorization: @client.anon_token, email:)
+      end
+    end
+  end
+end

data/lib/volcano/auth_reset_password.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Recovery-token password reset behavior for the authentication facade.
+  class Auth
+    def reset_password(token:, new_password:)
+      Transport.body(reset_password_response(token:, new_password:), 200)
+      nil
+    end
+
+    private
+
+    def reset_password_response(token:, new_password:)
+      Transport.invoke do
+        @transport.auth_reset_password(
+          authorization: @client.anon_token,
+          token: token,
+          new_password: new_password
+        )
+      end
+    end
+  end
+end

data/lib/volcano/auth_reset_password_for_email.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Password-reset request behavior for the authentication facade.
+  class Auth
+    def reset_password_for_email(email:)
+      Transport.body(reset_password_for_email_response(email:), 200)
+      nil
+    end
+
+    private
+
+    def reset_password_for_email_response(email:)
+      Transport.invoke do
+        @transport.auth_forgot_password(authorization: @client.anon_token, email: email)
+      end
+    end
+  end
+end

data/lib/volcano/auth_sessions.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Volcano
+  # Maps the internal wire response to immutable public session values.
+  module SessionPageMapping
+    SESSION_FIELDS = %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
+    REQUIRED_SESSION_FIELDS = SESSION_FIELDS.first(6).freeze
+
+    private
+
+    def session_page(body)
+      raise TypeError, 'Expected a complete session page' unless body.is_a?(Hash)
+
+      sessions = body.fetch('sessions')
+      raise TypeError, 'Expected a complete session page' unless sessions.is_a?(Array)
+
+      SessionPage.new(
+        sessions: sessions.map { |attributes| auth_session(attributes) },
+        total: body.fetch('total'), page: body.fetch('page'), limit: body.fetch('limit'),
+        total_pages: body.fetch('total_pages')
+      )
+    rescue KeyError
+      raise TypeError, 'Expected a complete session page'
+    end
+
+    def auth_session(attributes)
+      raise TypeError, 'Expected a complete authentication session' unless attributes.is_a?(Hash)
+
+      required = REQUIRED_SESSION_FIELDS.to_h { |name| [name, attributes.fetch(name.to_s)] }
+      optional = (SESSION_FIELDS - REQUIRED_SESSION_FIELDS).to_h do |name|
+        [name, attributes[name.to_s]]
+      end
+      AuthSession.new(**required, **optional)
+    rescue KeyError
+      raise TypeError, 'Expected a complete authentication session'
+    end
+  end
+  private_constant :SessionPageMapping
+
+  # Multi-device session behavior for the authentication facade.
+  class Auth
+    include SessionPageMapping
+
+    def list_sessions(page: 1, limit: 20)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      body = Transport.body(list_sessions_response(current.access_token, page, limit), 200)
+      result = session_page(body)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    def delete_all_other_sessions
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      Transport.body(delete_all_other_sessions_response(current.access_token), 204)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+    end
+
+    def delete_session(session_id)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      deletes_current = same_session_id?(current.access_token, session_id)
+      error = delete_session_error(current.access_token, session_id)
+      current_unchanged = session_unchanged_after_deletion?(deletes_current, error, generation)
+      raise Error::SessionChangedError, cause: error unless current_unchanged
+
+      raise error if error
+    end
+
+    private
+
+    def list_sessions_response(access_token, page, limit)
+      Transport.invoke do
+        @transport.auth_get_my_sessions(
+          authorization: access_token,
+          page: page,
+          limit: limit
+        )
+      end
+    end
+
+    def delete_all_other_sessions_response(access_token)
+      Transport.invoke do
+        @transport.auth_delete_all_my_sessions(authorization: access_token)
+      end
+    end
+
+    def delete_session_response(access_token, session_id)
+      Transport.invoke do
+        @transport.auth_delete_my_session(
+          authorization: access_token,
+          session_id: session_id
+        )
+      end
+    end
+
+    def delete_session_error(access_token, session_id)
+      Transport.body(delete_session_response(access_token, session_id), 204)
+      nil
+    rescue Error::VolcanoError => e
+      e
+    end
+
+    def session_unchanged_after_deletion?(deletes_current, error, generation)
+      uncertain = error.nil? || error.is_a?(Error::TransportError)
+      return @client.clear_session_if_current?(generation) if deletes_current && uncertain
+
+      @client.capture_session.first == generation
+    end
+
+    def same_session_id?(access_token, session_id)
+      current_session_id = access_token_session_id(access_token)
+      session_id.is_a?(String) && current_session_id&.casecmp?(session_id)
+    end
+
+    def access_token_session_id(access_token)
+      parts = access_token.split('.')
+      return unless parts.length == 3
+
+      encoded = parts.fetch(1).tr('-_', '+/')
+      padding = '=' * (-encoded.length % 4)
+      payload = JSON.parse((encoded + padding).unpack1('m0'))
+      session_id = payload['session_id']
+      session_id if session_id.is_a?(String) && !session_id.empty?
+    rescue ArgumentError, JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/volcano/auth_sign_up.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Session-less sign-up behavior for the authentication facade.
+  class Auth
+    INVALID_SIGN_UP_RESULT = 'Expected a complete sign-up acknowledgement'
+    private_constant :INVALID_SIGN_UP_RESULT
+
+    def sign_up(email:, password:, metadata: {}, sign_in_when_allowed: false)
+      generation, = @client.capture_session
+      payload = Transport.body(sign_up_response(email:, password:, metadata:), 201)
+      result = build_sign_up_result(payload)
+      return result unless sign_in_when_allowed && !result.confirmation_required
+
+      result.with(session: sign_in_for_generation(email:, password:, generation:))
+    end
+
+    private
+
+    def sign_up_response(email:, password:, metadata:)
+      Transport.invoke do
+        @transport.auth_signup(
+          authorization: @client.anon_token,
+          email: email,
+          password: password,
+          metadata: Hash(metadata)
+        )
+      end
+    end
+
+    def build_sign_up_result(payload)
+      confirmation_required = payload.fetch('confirmation_required')
+      message = payload.fetch('message')
+      valid = [true, false].include?(confirmation_required) && message.is_a?(String)
+      raise TypeError, INVALID_SIGN_UP_RESULT unless valid
+
+      SignUpResult.new(confirmation_required: confirmation_required, message: message.dup.freeze)
+    end
+  end
+end

data/lib/volcano/auth_state.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Idempotent handle for an authentication-state subscription.
+  class AuthSubscription
+    def initialize(&unsubscribe)
+      @unsubscribe = unsubscribe
+      @mutex = Mutex.new
+    end
+
+    def unsubscribe
+      callback = @mutex.synchronize do
+        current = @unsubscribe
+        @unsubscribe = nil
+        current
+      end
+      callback&.call
+      nil
+    end
+  end
+
+  # Owns synchronized local session state and its subscribers.
+  class AuthState
+    CALLBACK_FAILURES = [Exception].freeze
+    private_constant :CALLBACK_FAILURES
+
+    def initialize
+      @mutex = Mutex.new
+      @generation = 0
+      @lineage = 0
+      @session = nil
+      @callbacks = {}
+      @next_callback_id = 0
+      @notifications = []
+      @dispatching_notifications = false
+    end
+
+    def current = capture.last
+
+    def capture = @mutex.synchronize { [@generation, @session] }
+
+    def capture_binding = @mutex.synchronize { [@generation, @lineage, @session] }
+
+    def store(session, event: :signed_in)
+      dispatch = @mutex.synchronize do
+        enqueue_notification(replace(session, event), event, session)
+      end
+      drain_notifications if dispatch
+    end
+
+    def store_if_current?(session, generation, event: :signed_in, notifications: nil)
+      dispatch = @mutex.synchronize do
+        callbacks = replace_if_current(session, generation, event)
+        return false unless callbacks
+
+        enqueue_notification(callbacks, event, session)
+      end
+      return true unless dispatch
+
+      notifications ? notifications.push(method(:drain_notifications)) : drain_notifications
+      true
+    end
+
+    def subscribe(&callback)
+      callback_id, dispatch = @mutex.synchronize do
+        id, current = register(callback)
+        [id, enqueue_notification([id], :initial_session, current)]
+      end
+      drain_notifications if dispatch
+      AuthSubscription.new { unsubscribe(callback_id) }
+    end
+
+    private
+
+    def replace(session, event)
+      @session = session
+      @generation += 1
+      @lineage += 1 unless event == :token_refreshed
+      @callbacks.keys
+    end
+
+    def replace_if_current(session, generation, event)
+      return unless generation == @generation
+
+      replace(session, event)
+    end
+
+    def register(callback)
+      callback_id = @next_callback_id
+      @next_callback_id += 1
+      @callbacks[callback_id] = callback
+      [callback_id, @session]
+    end
+
+    def unsubscribe(callback_id)
+      @mutex.synchronize { @callbacks.delete(callback_id) }
+    end
+
+    def enqueue_notification(callbacks, event, session)
+      return false if event.nil? || callbacks.empty?
+
+      @notifications << [callbacks, event, session]
+      return false if @dispatching_notifications
+
+      @dispatching_notifications = true
+    end
+
+    def drain_notifications
+      failure = nil
+      loop do
+        notification = next_notification
+        break unless notification
+
+        current_failure = notify(*notification)
+        failure ||= current_failure
+      end
+      raise failure if failure
+    end
+
+    def next_notification
+      @mutex.synchronize do
+        if @notifications.empty?
+          @dispatching_notifications = false
+          return
+        end
+        @notifications.shift
+      end
+    end
+
+    def notify(callback_ids, event, session)
+      failure = nil
+      callback_ids.each do |callback_id|
+        notify_callback(callback_id, event, session)
+      rescue StandardError => e
+        Warning.warn("Volcano auth-state callback failed (#{e.class})\n")
+      rescue *CALLBACK_FAILURES => e
+        unsubscribe(callback_id)
+        failure ||= e
+      end
+      failure
+    end
+
+    def notify_callback(callback_id, event, session)
+      callback = @mutex.synchronize { @callbacks[callback_id] }
+      callback&.call(event, session)
+    end
+  end
+end

data/lib/volcano/auth_update_user.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Current-user update behavior for the authentication facade.
+  class Auth
+    def update_user(password: nil, metadata: nil)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      payload = Transport.body(
+        update_user_response(current.access_token, password:, metadata:),
+        200
+      )
+      user = build_user(user_payload(payload))
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      user
+    end
+
+    private
+
+    def update_user_response(access_token, password:, metadata:)
+      Transport.invoke do
+        @transport.auth_update_user(
+          authorization: access_token,
+          password: password,
+          metadata: metadata
+        )
+      end
+    end
+  end
+end

data/lib/volcano/client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Entry point for Volcano API, storage, lock, and realtime operations.
+  class Client
+    SessionToken = Data.define(:value) do
+      def session_token = value
+
+      def session_request
+        yield(value)
+      end
+    end
+    private_constant :SessionToken
+
+    attr_reader :auth, :functions, :logs, :storage, :locks, :realtime
+
+    def initialize(
+      anon_key:,
+      api_url: 'https://api.volcano.dev',
+      service_key: nil,
+      timeout: 60,
+      **adapters
+    )
+      transport, socket_factory, reconnect_delay = extract_adapters(adapters)
+      @api_url = api_url.delete_suffix('/')
+      @anon_key = anon_key
+      @service_key = service_key
+      @auth_state = AuthState.new
+      @transport = transport || GeneratedTransport.new(api_url: @api_url, timeout: timeout)
+      initialize_facades(socket_factory, reconnect_delay)
+    end
+
+    def database(name)
+      Database.new(self, @transport, name)
+    end
+
+    def anon_token
+      @anon_key
+    end
+
+    def current_session
+      @auth_state.current
+    end
+
+    def session_token
+      session = current_session
+      raise Error::AuthenticationError, 'No active session' unless session
+
+      session.access_token
+    end
+
+    def session_request(&)
+      @auth.session_request(&)
+    end
+
+    alias session_read session_request
+
+    def service_token
+      raise Error::AuthenticationError, 'No service key configured' unless @service_key
+
+      @service_key
+    end
+
+    def function_token
+      current_session&.access_token || @service_key || @anon_key
+    end
+
+    def store_session(session, event: :signed_in)
+      @auth_state.store(session, event: event)
+    end
+
+    def capture_session
+      @auth_state.capture
+    end
+
+    def capture_session_binding
+      @auth_state.capture_binding
+    end
+
+    def store_session_if_current?(session, generation, event: :signed_in, notifications: nil)
+      @auth_state.store_if_current?(session, generation, event: event, notifications: notifications)
+    end
+
+    def clear_session_if_current?(generation, event: :signed_out, notifications: nil)
+      @auth_state.store_if_current?(nil, generation, event: event, notifications: notifications)
+    end
+
+    def subscribe_auth_state_change(...)
+      @auth_state.subscribe(...)
+    end
+
+    private
+
+    def database_with_token(name, token)
+      Database.new(SessionToken.new(value: token), @transport, name)
+    end
+
+    def extract_adapters(adapters)
+      transport = adapters.delete(:_transport)
+      socket_factory = adapters.delete(:_realtime_socket_factory)
+      reconnect_delay = adapters.delete(:_realtime_reconnect_delay)
+      raise ArgumentError, "unknown keyword: #{adapters.keys.first}" unless adapters.empty?
+
+      [transport, socket_factory, reconnect_delay]
+    end
+
+    def initialize_facades(socket_factory, reconnect_delay)
+      @auth = Auth.new(self, @transport, api_url: @api_url)
+      @functions = Functions.new(self, @transport, api_url: @api_url)
+      @logs = Logs.new(self, @transport)
+      @storage = Storage.new(self, @transport, api_url: @api_url, anon_key: @anon_key)
+      @locks = Locks.new(self, @transport)
+      @realtime = Realtime.new(
+        self,
+        api_url: @api_url,
+        socket_factory: socket_factory,
+        reconnect_delay: reconnect_delay
+      )
+    end
+  end
+end