volcano-sdk 0.33.0 → 0.35.0

data/lib/volcano/realtime/protocol.rb

@@ -16,10 +16,14 @@ module Volcano
 
       # @dynamic code
 
-      def initialize(message, code: nil)
+      def initialize(message, code: nil, temporary: false)
         super(message)
         @code = code.is_a?(String) ? code.dup.freeze : code
+        @temporary = temporary == true
       end
+
+      # Whether the server expects the same command to succeed later.
+      def temporary? = @temporary
     end
 
     class ClosedError < StandardError; end
@@ -93,12 +97,12 @@ module Volcano
         result.tap { @connected = true }
       end
 
-      def subscribe(channel:, recoverable: false, join_leave: false, recovery: nil)
+      def subscribe(channel:, recoverable: false, join_leave: false, recovery: nil, data: nil)
         @subscription_lock.acquire do
           ensure_open!
           raise DuplicateSubscriptionError, "already subscribed to #{channel}" if @subscriptions.include?(channel)
 
-          result = subscribe_request(channel:, recoverable:, join_leave:, recovery:)
+          result = subscribe_request(channel:, recoverable:, join_leave:, recovery:, data:)
           ensure_open!
           @subscriptions.add(channel)
           result

data/lib/volcano/realtime/protocol_dispatch.rb

@@ -59,7 +59,7 @@ module Volcano
         raise TypeError, 'realtime error must be an object' unless error.is_a?(Hash)
 
         message = error['message'] || 'realtime command failed'
-        Protocol::Failure.new(error: ServerError.new(message, code: error['code']))
+        Protocol::Failure.new(error: ServerError.new(message, code: error['code'], temporary: error['temporary']))
       end
 
       def successful_reply(frame, reply_key)

data/lib/volcano/realtime/protocol_io.rb

@@ -10,11 +10,13 @@ module Volcano
 
         private
 
-        def request(reply_key, on_reply: nil)
+        # on_write runs once the frame holds the write lock, when the server may
+        # start to receive it.
+        def request(reply_key, on_reply: nil, on_write: nil)
           # @type var registered_id: Integer?
           ensure_open!
           registered_id, reply_queue = register_request(reply_key, on_reply)
-          write_frame(yield(registered_id || raise(TypeError, 'invalid realtime request id')))
+          write_frame(yield(registered_id || raise(TypeError, 'invalid realtime request id')), on_write)
           reply = await_reply(reply_queue)
           raise reply.error if reply.is_a?(Failure)
 
@@ -36,10 +38,11 @@ module Volcano
           [@next_id, queue]
         end
 
-        def write_frame(frame) = write_serialized_frame("#{JSON.generate(frame)}\n")
+        def write_frame(frame, on_write = nil) = write_serialized_frame("#{JSON.generate(frame)}\n", on_write)
 
-        def write_serialized_frame(frame)
+        def write_serialized_frame(frame, on_write = nil)
           @write_lock.acquire do
+            on_write&.call
             @socket.write(frame)
             @socket.flush
           end

data/lib/volcano/realtime/protocol_lifecycle.rb

@@ -9,6 +9,13 @@ module Volcano
         # @dynamic dispatch_publication_batches, read_loop
         def connected? = @connected && !@closed
 
+        # Ends the connection from the reader, as a loss would, so the reconnect
+        # runs in the protocol's tasks rather than the caller's.
+        def drop
+          close_socket
+          nil
+        end
+
         def on_publication(channel, on_rejection: nil, &handler)
           ensure_open!
           @publication_handlers[channel] << ProtocolPublicationDispatch::Registration.new(

data/lib/volcano/realtime/protocol_recovery.rb

@@ -6,27 +6,38 @@ module Volcano
     module ProtocolRecovery
       # @dynamic class, request, dispatch_recovered_publications, recovery_position
       # @dynamic delete_recovery_state, set_recovery_position, mark_unknown_gap
-      # @dynamic mark_publication_gap, same_epoch?
+      # @dynamic mark_publication_gap, same_epoch?, close_socket
 
       private
 
-      def subscribe_request(channel:, recoverable:, join_leave:, recovery:)
-        on_reply = nil
-        if recovery
-          on_reply = lambda do |reply|
-            publications = parse_recovery_result(channel: channel, recovery: recovery, result: reply)
-            dispatch_recovered_publications(channel, publications)
-          end
-        end
-
-        request('subscribe', on_reply:) do |id|
-          self.class.subscribe(
+      def subscribe_request(channel:, recoverable:, join_leave:, recovery:, data:)
+        writing = false
+        request('subscribe', on_reply: recovery_reply(channel, recovery), on_write: -> { writing = true }) do |id|
+          command = self.class.subscribe(
             id: id,
             channel: channel,
             recoverable: recoverable,
             join_leave: join_leave,
             recovery: recovery
           )
+          command['subscribe']['data'] = data if data
+          command
+        end
+      rescue Async::Cancel
+        # Once the frame is being written the server may subscribe, and nothing
+        # would leave the channel. Closing the socket has the reader end the
+        # connection, as on a loss, so the reconnect is not cancelled along with
+        # this task. Stopped before that, there is nothing to leave.
+        close_socket if writing
+        raise
+      end
+
+      def recovery_reply(channel, recovery)
+        return unless recovery
+
+        lambda do |reply|
+          publications = parse_recovery_result(channel: channel, recovery: recovery, result: reply)
+          dispatch_recovered_publications(channel, publications)
         end
       end
 

data/lib/volcano/realtime.rb

@@ -16,6 +16,7 @@ require_relative 'realtime/postgres_batch'
 require_relative 'realtime/postgres_delivery'
 require_relative 'realtime/broadcast_delivery'
 require_relative 'realtime/channel_callbacks'
+require_relative 'realtime/durable_channel'
 
 module Volcano
   # Manages a project's realtime connection and broadcast channels.
@@ -68,6 +69,9 @@ module Volcano
     end
 
     CHANNEL_TYPES = %i[broadcast presence postgres].freeze
+    # A channel that fetches no rows still takes a batch configuration.
+    UNBATCHED = PostgresBatchConfig.new(auto_fetch: false, batch_window_ms: 1, max_batch_size: 1)
+    private_constant :UNBATCHED
 
     # Owns the public realtime facade and its channel collection.
     module Core
@@ -152,6 +156,8 @@ module Volcano
 
       def report_channel_error(error) = protocol_error(public_error(error))
 
+      def blocking(&) = BlockingCall.call(&)
+
       def cached_channel(channel, batch_config)
         channel.__send__(:ensure_fetch_config!, batch_config)
         channel
@@ -161,6 +167,20 @@ module Volcano
         Channel.new(self, -> { protocol }, name, type, batch_config:)
       end
 
+      # Opens the channel an execution publishes its messages on, or answers
+      # nil when this client already follows the execution.
+      def durable_channel(execution_id, client_token, follower)
+        channel_lock.acquire do
+          ensure_open!
+          name = "durable:#{execution_id}"
+          next if @channels.key?(name)
+
+          channel = build_channel(name, :durable, UNBATCHED)
+          channel.__send__(:follow_durable, client_token && { 'client_token' => client_token }, follower)
+          @channels[name] = channel
+        end
+      end
+
       def protocol_lock
         require 'async/semaphore'
         @protocol_lock ||= Async::Semaphore.new(1)
@@ -186,6 +206,7 @@ module Volcano
       include PostgresDelivery
       include BroadcastDelivery
       include ChannelCallbacks
+      include DurableChannel
 
       attr_reader :name
 
@@ -194,7 +215,7 @@ module Volcano
         @protocol_provider = protocol_provider
         @name = name.freeze
         @handler_registered = @subscribed = @subscription_desired = @closed = false
-        @lifecycle_lock = nil
+        @lifecycle_lock = @subscribe_data = @follower = nil
         initialize_recovery_state
         initialize_callback_dispatch
         initialize_presence(type)
@@ -230,13 +251,13 @@ module Volcano
       def restoration_needed? = subscription_desired? && !@subscribed
 
       def restore_subscription(protocol)
-        state = with_lifecycle_lock do
-          restoration_needed? ? subscribe_protocol(protocol) : nil
-        end
-        if state
-          subscribed_protocol, epoch = state
-          sync_presence(subscribed_protocol, epoch)
-        end
+        ask_follower_to_restore
+        state = resubscribe(protocol)
+        return unless state
+
+        subscribed_protocol, epoch = state
+        sync_presence(subscribed_protocol, epoch)
+        @follower&.resubscribed
         nil
       end
 
@@ -247,6 +268,7 @@ module Volcano
           clear_broadcast_recovery_state
           clear_channel_recovery_state
           mark_removed
+          @follower&.close
         end
         nil
       end
@@ -273,6 +295,18 @@ module Volcano
         raise
       end
 
+      # Outside the lifecycle lock: a follower that refuses may leave the channel.
+      def ask_follower_to_restore
+        @follower&.restoring if restoration_needed?
+      end
+
+      # The refusal is handled outside the lifecycle lock too, for the same reason.
+      def resubscribe(protocol)
+        with_lifecycle_lock { restoration_needed? ? subscribe_protocol(protocol) : nil }
+      rescue ServerError => e
+        raise restore_refused(e)
+      end
+
       def with_lifecycle_lock(&)
         require 'async/semaphore'
         lock = @lifecycle_lock ||= Async::Semaphore.new(1)

data/lib/volcano/redaction.rb

@@ -25,7 +25,7 @@ module Volcano
         return copy_volcano_error(error, redacted_message)
       end
       if defined?(Realtime::ServerError) && error.is_a?(Realtime::ServerError)
-        return error.class.new(redacted_message, code: error.code)
+        return error.class.new(redacted_message, code: error.code, temporary: error.temporary?)
       end
 
       error.exception(redacted_message)

data/lib/volcano/sandbox_deployment_response.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Validate custom-image deployment responses before exposing typed values.
+  module SandboxDeploymentResponse
+    def self.deployment(value)
+      data = Transport.json_object(value)
+      SandboxDeployment.new(id: SandboxResponse.text(data['id']), status: SandboxResponse.text(data['status']),
+                            created_at: SandboxResponse.text(data['created_at']),
+                            updated_at: SandboxResponse.text(data['updated_at']))
+    end
+
+    def self.page(value)
+      data = Transport.json_object(value)
+      pagination = Transport.json_object(data['pagination'])
+      SandboxDeploymentPage.new(data: SandboxResponse.array(data['data']).map { |row| deployment(row) }.freeze,
+                                limit: SandboxResponse.integer(pagination['limit']),
+                                has_more: SandboxResponse.flag(pagination['has_more']),
+                                next_cursor: optional_text(pagination['next_cursor']))
+    end
+
+    def self.logs(value)
+      data = Transport.json_object(value)
+      SandboxBuildLogPage.new(data: SandboxResponse.array(data['data']).map { |row| log(row) }.freeze,
+                              next_cursor: optional_text(data['next_cursor']))
+    end
+
+    def self.log(value)
+      data = Transport.json_object(value)
+      SandboxBuildLog.new(timestamp: SandboxResponse.text(data['timestamp']),
+                          message: SandboxResponse.text(data['message']))
+    end
+
+    def self.optional_text(value)
+      value.nil? ? nil : SandboxResponse.text(value)
+    end
+    private_class_method :log, :optional_text
+  end
+end

data/lib/volcano/sandbox_deployments.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Build, inspect, and export custom templates from source archives.
+  module SandboxDeployments
+    def deploy( # rubocop:disable Metrics/ParameterLists -- Preserve explicit typed facade keywords.
+      project_id, sandbox_id, source, name:, memory_mb: 1024, ports: [], request_id: nil
+    )
+      validate_source(source, ports)
+      # @type var options: sandbox_request_options
+      options = { operation: :deploy_sandbox, archive: source.dup.freeze,
+                  body: { name: name, memory_mb: memory_mb, ports: ports },
+                  request_id: SandboxRequests.request_id({ request_id: request_id }.compact) }
+      request = deployment_request(project_id, sandbox_id, options)
+      SandboxDeploymentResponse.deployment(@requests.service_scope.call(request, status: 202))
+    end
+
+    def deployments(project_id, sandbox_id, cursor: nil, limit: 10)
+      request = deployment_request(project_id, sandbox_id,
+                                   { operation: :list_sandbox_deployments, cursor: cursor, limit: limit })
+      SandboxDeploymentResponse.page(@requests.service_scope.call(request))
+    end
+
+    def deployment(project_id, sandbox_id, deployment_id)
+      request = deployment_request(project_id, sandbox_id, operation: :get_sandbox_deployment,
+                                                           deployment_id: SandboxRequests.identifier(deployment_id))
+      SandboxDeploymentResponse.deployment(@requests.service_scope.call(request))
+    end
+
+    def source(project_id, sandbox_id, deployment_id)
+      request = deployment_request(project_id, sandbox_id, operation: :get_sandbox_deployment_source,
+                                                           deployment_id: SandboxRequests.identifier(deployment_id))
+      SandboxResponse.text(@requests.service_scope.call(request)).b
+    end
+
+    def logs( # rubocop:disable Metrics/ParameterLists -- Preserve explicit typed facade keywords.
+      project_id, sandbox_id, deployment_id, region:, cursor: nil, limit: 100
+    )
+      # @type var options: sandbox_request_options
+      options = { operation: :get_sandbox_deployment_logs, deployment_id: SandboxRequests.identifier(deployment_id),
+                  region: region, cursor: cursor, limit: limit }
+      SandboxDeploymentResponse.logs(@requests.service_scope.call(deployment_request(project_id, sandbox_id, options)))
+    end
+
+    def delete_template(project_id, sandbox_id)
+      @requests.service_scope.call(deployment_request(project_id, sandbox_id, operation: :delete_sandbox), status: 202)
+      nil
+    end
+
+    private
+
+    def deployment_request(project_id, sandbox_id, options)
+      options[:resource_id] = SandboxRequests.identifier(project_id)
+      options[:subject_id] = SandboxRequests.identifier(sandbox_id)
+      SandboxRequest.new(options)
+    end
+
+    def validate_source(source, ports)
+      if source.bytesize > 32 * 1024 * 1024
+        raise Error::ValidationError, 'Sandbox source archives are limited to 32 MiB'
+      end
+
+      validate_ports(ports)
+    end
+
+    def validate_ports(ports)
+      if ports.length > 16 || ports.uniq.length != ports.length
+        raise Error::ValidationError, 'Sandbox ports must be unique and contain at most 16 entries'
+      end
+      return if ports.all? { |port| valid_port?(port) }
+
+      raise Error::ValidationError, 'Sandbox ports must be between 1 and 65532'
+    end
+
+    def valid_port?(port)
+      port.is_a?(Integer) && port.between?(1, 65_532)
+    end
+  end
+end

data/lib/volcano/sandbox_models.rb

@@ -8,6 +8,14 @@ module Volcano
                                        :stderr_truncated, :session_id, :region, :duration_ms)
   # A published preset and its available memory and regions.
   SandboxPreset = Data.define(:id, :memory_mb, :regions)
+  # Immutable build status for a custom template version.
+  SandboxDeployment = Data.define(:id, :status, :created_at, :updated_at)
+  # A page of custom template versions.
+  SandboxDeploymentPage = Data.define(:data, :limit, :has_more, :next_cursor)
+  # One regional build message.
+  SandboxBuildLog = Data.define(:timestamp, :message)
+  # A page of regional build output.
+  SandboxBuildLogPage = Data.define(:data, :next_cursor)
   # Expiring HTTP access credentials are redacted from inspection.
   class SandboxAccess
     attr_reader :url, :token, :expires_at

data/lib/volcano/sandbox_request.rb

@@ -19,6 +19,12 @@ module Volcano
     def subject_id = @options[:subject_id]
     def body = @options[:body]
     def request_id = @options[:request_id]
+    def deployment_id = @options[:deployment_id]
+    def archive = @options.fetch(:archive)
+    def deployment_body = @options.fetch(:body)
+    def cursor = @options[:cursor]
+    def region = @options[:region]
+    def limit = @options[:limit]
     def timeout = @options.fetch(:timeout, 0)
   end
 

data/lib/volcano/sandboxes.rb

@@ -3,6 +3,8 @@
 module Volcano
   # Create isolated sessions or execute a command to completion.
   class Sandboxes
+    include SandboxDeployments
+
     def initialize(client, transport)
       @requests = SandboxRequests.new(client, transport)
     end

data/lib/volcano/storage_mutations.rb

@@ -79,8 +79,8 @@ module Volcano
     end
 
     def visibility_value(value)
-      return true if value == true
-      return false if value == false
+      return true if value.equal?(true)
+      return false if value.equal?(false)
 
       raise ArgumentError, 'public must be true or false'
     end

data/lib/volcano/storage_object_response.rb

@@ -50,8 +50,8 @@ module Volcano
     end
 
     def storage_boolean(value)
-      return true if value == true
-      return false if value == false
+      return true if value.equal?(true)
+      return false if value.equal?(false)
 
       raise Error::TransportError, 'invalid storage boolean'
     end

data/lib/volcano/transport.rb

@@ -11,7 +11,7 @@ module Volcano
     ERROR_TYPES = {
       400 => Error::ValidationError,
       401 => Error::AuthenticationError,
-      403 => Error::AuthenticationError,
+      403 => Error::PermissionDeniedError,
       404 => Error::NotFoundError,
       409 => Error::ConflictError,
       422 => Error::ValidationError,

data/lib/volcano/version.rb

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

data/lib/volcano.rb

@@ -8,6 +8,8 @@ require_relative 'volcano/session'
 require_relative 'volcano/session_credentials'
 require_relative 'volcano/function_response'
 require_relative 'volcano/durable_models'
+require_relative 'volcano/durable_approval_models'
+require_relative 'volcano/durable_message_models'
 require_relative 'volcano/log_responses'
 require_relative 'volcano/storage_models'
 require_relative 'volcano/storage_upload_models'
@@ -44,6 +46,16 @@ require_relative 'volcano/auth_reset_password'
 require_relative 'volcano/database'
 require_relative 'volcano/function_resolution'
 require_relative 'volcano/functions'
+require_relative 'volcano/durable_arguments'
+require_relative 'volcano/durable_approval_responses'
+require_relative 'volcano/durable_approvals'
+require_relative 'volcano/durable_message_arguments'
+require_relative 'volcano/durable_message_responses'
+require_relative 'volcano/durable_message_catch_ups'
+require_relative 'volcano/durable_message_backlog'
+require_relative 'volcano/durable_message_stream'
+require_relative 'volcano/durable_message_session'
+require_relative 'volcano/durable_messages'
 require_relative 'volcano/durable'
 require_relative 'volcano/logs'
 require_relative 'volcano/storage_session_adapter'
@@ -69,6 +81,8 @@ require_relative 'volcano/sandbox_request'
 require_relative 'volcano/sandbox_response'
 require_relative 'volcano/sandbox_files'
 require_relative 'volcano/sandbox_session'
+require_relative 'volcano/sandbox_deployment_response'
+require_relative 'volcano/sandbox_deployments'
 require_relative 'volcano/sandboxes'
 require_relative 'volcano/client'
 

data/sig/core_facades.rbs

@@ -1,6 +1,8 @@
 module Volcano
   type sdk_json = nil | bool | Integer | Float | String | Time | Array[sdk_json] | Hash[String | Symbol, sdk_json]
   type sdk_payload = Hash[String | Symbol, sdk_json]
+  type durable_message_filters = { ?direction: (String | Symbol)?, ?name: String?, ?after: Integer?, ?limit: Integer?, ?client_token: String?, ?project_id: String? }
+  type durable_approval_filters = { ?status: String?, ?function: String?, ?execution_id: String?, ?from: (Time | String)?, ?to: (Time | String)?, ?page: Integer?, ?limit: Integer? }
   type database_rows = Array[Hash[String, json_value]]
 
   class Database
@@ -67,7 +69,34 @@ module Volcano
     def invoke: (String name, ?sdk_payload payload) -> FunctionResponse
   end
 
+  class DurableApprovals
+    MAX_FUNCTION_LENGTH: Integer
+    MAX_COMMENT_LENGTH: Integer
+
+    def list: (String project_id, ?durable_approval_filters filters) -> DurableApprovalPage
+    def get: (String project_id, String approval_id) -> DurableApproval
+    def stats: (String project_id, ?function: String?, ?from: (Time | String)?, ?to: (Time | String)?) -> DurableApprovalStats
+    def approve: (String project_id, String approval_id, ?comment: String?) -> DurableApproval
+    def deny: (String project_id, String approval_id, ?comment: String?) -> DurableApproval
+  end
+
+  class DurableMessageSubscription
+    def unsubscribe: () -> nil
+    def inspect: () -> String
+    def to_s: () -> String
+    def pretty_print: (DurableExecution::_PrettyPrinter printer) -> void
+  end
+
+  class DurableMessages
+    def send_message: (String function_name, String execution_id, String name, ?sdk_json data, **String? options) -> DurableMessage
+    def list: (String function_name, String execution_id, ?durable_message_filters filters) -> DurableMessagePage
+    def subscribe: (String function_name, String execution_id, ?client_token: String?, ?project_id: String?) { (DurableMessage) -> void } -> DurableMessageSubscription
+  end
+
   class Durable
+    attr_reader approvals: DurableApprovals
+    attr_reader messages: DurableMessages
+
     def start: (String function_name, ?sdk_payload payload, ?execution_name: String?) -> DurableExecution
     def get: (String project_id, String function_name, String execution_id) -> DurableExecution
     def list: (String project_id, String function_name, ?status: String?, ?page: Integer?, ?limit: Integer?) -> DurableExecutionPage