volcano-sdk 0.5.2

data/lib/volcano/storage_mutations.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Mutation operations for one storage bucket.
+  class StorageBucket
+    def remove(paths)
+      deleted = storage_paths(paths)
+      authorization = @client.session_token
+      deleted.each { |path| delete_path(path, authorization) }
+      deleted
+    end
+
+    def move(from_path, to_path)
+      source, destination = storage_paths([from_path, to_path])
+      response = Transport.invoke do
+        @transport.move_storage_object(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          from_path: source,
+          to_path: destination
+        )
+      end
+      storage_object(Transport.body(response, 200))
+    end
+
+    def copy(from_path, to_path)
+      source, destination = storage_paths([from_path, to_path])
+      response = Transport.invoke do
+        @transport.copy_storage_object(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          from_path: source,
+          to_path: destination
+        )
+      end
+      storage_object(Transport.body(response, 201))
+    end
+
+    def update_visibility(path, public:)
+      object_path = storage_paths(path).fetch(0)
+      visibility = visibility_value(public)
+      response = Transport.invoke do
+        @transport.update_storage_object_visibility(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          path: object_path,
+          is_public: visibility
+        )
+      end
+      storage_object(Transport.body(response, 200))
+    end
+
+    private
+
+    def storage_paths(paths)
+      path_list = paths.is_a?(String) ? [paths] : paths.to_a
+      if path_list.empty? || !path_list.all? { |path| path.is_a?(String) && !path.empty? }
+        raise ArgumentError, 'storage paths must be non-empty strings'
+      end
+
+      path_list.map { |path| path.dup.freeze }.freeze
+    end
+
+    def delete_path(path, authorization)
+      response = Transport.invoke do
+        @transport.delete_storage_object(
+          authorization: authorization,
+          bucket_name: @name,
+          path: path
+        )
+      end
+      Transport.body(response, 200)
+    end
+
+    def visibility_value(value)
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, 'public must be true or false'
+    end
+  end
+end

data/lib/volcano/storage_public_url.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'cgi'
+require 'json'
+
+module Volcano
+  # Local public URL construction for one storage bucket.
+  class StorageBucket
+    INVALID_PUBLIC_URL_ANON_KEY = 'Anon key must contain a project ID'
+    INVALID_PUBLIC_URL_PATH = 'Public URL paths cannot contain dot segments'
+    INVALID_STORAGE_PATH = 'storage path must be a non-empty string'
+    private_constant :INVALID_PUBLIC_URL_ANON_KEY, :INVALID_PUBLIC_URL_PATH, :INVALID_STORAGE_PATH
+
+    def get_public_url(path)
+      object_path = public_url_path(path)
+      segments = [project_id, @name, *public_url_path_segments(object_path)]
+      "#{@api_url}/public/#{segments.map { |segment| encode_segment(segment) }.join('/')}".freeze
+    end
+
+    private
+
+    def project_id
+      value = anon_key_payload['project_id']
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, INVALID_PUBLIC_URL_ANON_KEY
+    end
+
+    def anon_key_payload
+      parts = @anon_key.split('.')
+      raise ArgumentError, INVALID_PUBLIC_URL_ANON_KEY unless parts.length == 3
+
+      encoded = parts.fetch(1).tr('-_', '+/')
+      payload = JSON.parse(Base64.strict_decode64(pad_base64(encoded)))
+      return payload if payload.is_a?(Hash)
+
+      raise ArgumentError, INVALID_PUBLIC_URL_ANON_KEY
+    rescue ArgumentError, JSON::ParserError => e
+      raise ArgumentError, INVALID_PUBLIC_URL_ANON_KEY, cause: e
+    end
+
+    def pad_base64(encoded)
+      encoded + ('=' * (-encoded.length % 4))
+    end
+
+    def public_url_path_segments(path)
+      segments = path.split('/', -1)
+      raise ArgumentError, INVALID_PUBLIC_URL_PATH if segments.intersect?(%w[. ..])
+
+      segments
+    end
+
+    def public_url_path(path)
+      return path if path.is_a?(String) && !path.empty?
+
+      raise ArgumentError, INVALID_STORAGE_PATH
+    end
+
+    def encode_segment(segment)
+      CGI.escapeURIComponent(segment)
+    end
+  end
+end

data/lib/volcano/storage_resumable_upload.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'tempfile'
+
+module Volcano
+  # High-level resumable upload orchestration for one storage bucket.
+  class StorageBucket
+    SPOOL_READ_SIZE = 1_048_576
+    private_constant :SPOOL_READ_SIZE
+
+    def upload_resumable(
+      path,
+      value,
+      content_type: 'application/octet-stream',
+      part_size: nil,
+      on_progress: nil
+    )
+      with_resumable_upload_source(value) do |source, total_size|
+        session = create_upload_session(
+          path, total_size: total_size, content_type: content_type, part_size: part_size
+        )
+        upload_session_parts(path, source, session, total_size, on_progress)
+        complete_upload_session(path, session_id: session.session_id)
+      end
+    end
+
+    private
+
+    def upload_session_parts(path, source, session, total_size, on_progress)
+      uploaded = 0
+      session.total_parts.times do |part_index|
+        part = source.read(session.part_size)
+        upload_part(
+          path,
+          session_id: session.session_id,
+          part_number: part_index + 1,
+          data: part
+        )
+        uploaded += part.bytesize
+        on_progress&.call(uploaded, total_size)
+      end
+    rescue StandardError
+      abort_failed_upload(path, session.session_id)
+      raise
+    end
+
+    def abort_failed_upload(path, session_id)
+      abort_upload_session(path, session_id: session_id)
+    rescue Error::VolcanoError
+      nil
+    end
+
+    def with_resumable_upload_source(value, &)
+      return yield StringIO.new(value.b), value.bytesize if value.is_a?(String)
+      raise ArgumentError, 'upload data must be a String or IO' unless value.respond_to?(:read)
+
+      remaining = remaining_upload_bytes(value)
+      return yield value, remaining unless remaining.nil?
+
+      with_spooled_upload_source(value, &)
+    end
+
+    def remaining_upload_bytes(source)
+      return unless source.respond_to?(:size) && source.respond_to?(:pos)
+
+      source.size - source.pos
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def with_spooled_upload_source(source)
+      Tempfile.create('volcano-upload') do |file|
+        file.binmode
+        spool_upload_source(source, file)
+        file.rewind
+        yield file, file.size
+      end
+    end
+
+    def spool_upload_source(source, file)
+      loop do
+        chunk = source.read(SPOOL_READ_SIZE)
+        break if chunk.nil?
+
+        file.write(chunk)
+      end
+    end
+  end
+end

data/lib/volcano/storage_upload_sessions.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Resumable upload operations for one storage bucket.
+  class StorageBucket
+    def create_upload_session(
+      path,
+      total_size:,
+      content_type: 'application/octet-stream',
+      part_size: nil
+    )
+      request = UploadSessionRequest.new(
+        path: path,
+        content_type: content_type,
+        total_size: total_size,
+        part_size: part_size
+      )
+      response = Transport.invoke do
+        @transport.create_upload_session(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          request: request
+        )
+      end
+      upload_session(Transport.body(response, 201))
+    end
+
+    def upload_part(path, session_id:, part_number:, data:)
+      request = UploadPartRequest.new(
+        path: path,
+        session_id: session_id,
+        part_number: part_number,
+        data: upload_bytes(data)
+      )
+      response = Transport.invoke do
+        @transport.upload_part(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          request: request
+        )
+      end
+      upload_part_metadata(Transport.body(response, 200))
+    end
+
+    def complete_upload_session(path, session_id:)
+      request = UploadSessionReference.new(path: path, session_id: session_id)
+      response = Transport.invoke do
+        @transport.complete_upload_session(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          request: request
+        )
+      end
+      storage_object(Transport.body(response, 200).fetch('object'))
+    end
+
+    def get_upload_session(path, session_id:)
+      request = UploadSessionReference.new(path: path, session_id: session_id)
+      response = Transport.invoke do
+        @transport.get_upload_session(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          request: request
+        )
+      end
+      upload_session_status(Transport.body(response, 200))
+    end
+
+    def abort_upload_session(path, session_id:)
+      request = UploadSessionReference.new(path: path, session_id: session_id)
+      response = Transport.invoke do
+        @transport.abort_upload_session(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          request: request
+        )
+      end
+      Transport.body(response, 200)
+      nil
+    end
+
+    private
+
+    def upload_session(payload)
+      UploadSession.new(
+        session_id: payload.fetch('session_id'),
+        part_size: payload.fetch('part_size'),
+        total_parts: payload.fetch('total_parts'),
+        expires_at: parse_time(payload.fetch('expires_at'))
+      )
+    end
+
+    def upload_part_metadata(payload)
+      UploadPart.new(
+        part_number: payload.fetch('part_number'),
+        etag: payload.fetch('etag'),
+        size: payload.fetch('size')
+      )
+    end
+
+    def upload_session_status(payload)
+      attributes = upload_session_status_attributes(payload)
+      attributes[:parts] = attributes.fetch(:parts).map { |part| upload_part_metadata(part) }
+      attributes[:expires_at] = parse_time(attributes.fetch(:expires_at))
+      attributes[:created_at] = parse_time(attributes.fetch(:created_at))
+      UploadSessionStatus.new(**attributes)
+    end
+
+    def upload_session_status_attributes(payload)
+      UPLOAD_SESSION_STATUS_ATTRIBUTES.to_h do |name|
+        value = name == :parts ? payload.fetch(name.to_s, []) : payload.fetch(name.to_s)
+        [name, value]
+      end
+    end
+  end
+end

data/lib/volcano/transport.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require 'socket'
+
+module Volcano
+  # Normalizes transport responses and maps failures to public SDK errors.
+  module Transport
+    Response = Data.define(:status, :body, :headers, :data)
+
+    ERROR_TYPES = {
+      400 => Error::ValidationError,
+      401 => Error::AuthenticationError,
+      403 => Error::AuthenticationError,
+      404 => Error::NotFoundError,
+      409 => Error::ConflictError,
+      422 => Error::ValidationError,
+      429 => Error::RateLimitedError
+    }.freeze
+
+    NETWORK_ERRORS = [IOError, SystemCallError, SocketError, Timeout::Error].freeze
+
+    module_function
+
+    def invoke
+      yield
+    rescue *NETWORK_ERRORS => e
+      raise Error::TransportError, e.message, cause: e
+    end
+
+    def body(response, expected_status)
+      return response.body if response.status == expected_status
+
+      raise response_error(response)
+    end
+
+    def response_error(response)
+      payload = response.body.is_a?(Hash) ? response.body : {}
+      retry_after = integer_header(response.headers, 'Retry-After') if response.status == 429
+      error_type(response.status).new(
+        payload['error'] || payload['message'] || 'Volcano request failed',
+        status: response.status,
+        code: payload['code']&.to_s,
+        retry_after: retry_after
+      )
+    end
+
+    def error_type(status)
+      ERROR_TYPES.fetch(status) do
+        status.between?(500, 599) ? Error::ServerError : Error::VolcanoError
+      end
+    end
+
+    def integer_header(headers, name)
+      value = headers&.find { |key, _| key.casecmp?(name) }&.last
+      Integer(value, exception: false)
+    end
+    private_class_method :error_type, :integer_header, :response_error
+  end
+end

data/lib/volcano/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Volcano
+  VERSION = '0.5.2'
+end

data/lib/volcano.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'volcano/version'
+require_relative 'volcano/connection_string'
+require_relative 'volcano/models'
+require_relative 'volcano/function_response'
+require_relative 'volcano/log_responses'
+require_relative 'volcano/storage_models'
+require_relative 'volcano/auth_state'
+require_relative 'volcano/errors'
+require_relative 'volcano/redaction'
+require_relative 'volcano/transport'
+require_relative 'volcano/generated_transport'
+require_relative 'volcano/auth'
+require_relative 'volcano/auth_refresh'
+require_relative 'volcano/auth_sign_up'
+require_relative 'volcano/sign_up_result'
+require_relative 'volcano/auth_anonymous'
+require_relative 'volcano/auth_confirm_email'
+require_relative 'volcano/auth_resend_confirmation'
+require_relative 'volcano/auth_email_change'
+require_relative 'volcano/auth_sessions'
+require_relative 'volcano/auth_oauth'
+require_relative 'volcano/auth_oauth_sign_in'
+require_relative 'volcano/auth_hosted'
+require_relative 'volcano/auth_oauth_token'
+require_relative 'volcano/auth_oauth_api'
+require_relative 'volcano/auth_reset_password_for_email'
+require_relative 'volcano/auth_reset_password'
+require_relative 'volcano/auth_get_user'
+require_relative 'volcano/auth_update_user'
+require_relative 'volcano/database'
+require_relative 'volcano/function_resolution'
+require_relative 'volcano/functions'
+require_relative 'volcano/logs'
+require_relative 'volcano/storage'
+require_relative 'volcano/storage_upload_sessions'
+require_relative 'volcano/storage_resumable_upload'
+require_relative 'volcano/storage_mutations'
+require_relative 'volcano/storage_public_url'
+require_relative 'volcano/lock_lease_clock'
+require_relative 'volcano/lock_guard'
+require_relative 'volcano/lock_renewer'
+require_relative 'volcano/lock_session'
+require_relative 'volcano/lock_auto_renewal'
+require_relative 'volcano/locks'
+require_relative 'volcano/realtime/protocol'
+require_relative 'volcano/realtime'
+require_relative 'volcano/client'
+
+# Public namespace for the Volcano Ruby SDK.
+module Volcano
+  private_constant :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer, :LockSession,
+                   :Redaction
+
+  Realtime.private_constant :Protocol, :ProtocolDispatch, :ProtocolPublicationDispatch, :ProtocolRecovery,
+                            :ProtocolRecoveryDispatch, :ProtocolRecoveryPosition
+end