volcano-sdk 0.33.0 → 0.35.0

data/lib/volcano/durable_message_stream.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Delivers the messages a durable execution publishes in `seq` order, once
+  # each, from its realtime channel and from the messages list.
+  #
+  # A live message can only be delivered once everything before it has been
+  # listed, or the missed ones would fall below the last delivered `seq` and be
+  # skipped. So live messages are held until the first catch-up starts, while
+  # any catch-up is reading, and while any held message still follows a gap.
+  # A held message is released only once the message its broadcast names as
+  # the one before it has been delivered.
+  #
+  # After the first catch-up, every message is delivered from the stream's own
+  # task, one at a time. A live one is held and released there too, since a
+  # reconnect stops the connection's tasks midway and would leave the block's
+  # work on it unfinished.
+  #
+  # The channel itself drops publications while it is not subscribed, and
+  # reports each resubscription, which starts a catch-up of what it dropped.
+  # A broadcast naming a publish not yet delivered starts one too, since the
+  # broadcast before it was lost or has yet to arrive, and so does a
+  # publication the connection had no room for or that does not read as a
+  # message.
+  class DurableMessageStream
+    include DurableMessageResponses
+
+    Held = Data.define(:message, :prev_seq)
+    ENDED = 'the durable message subscription has ended'
+    private_constant :Held, :ENDED
+
+    # +list_after+ reads the page of published messages after a `seq`, and
+    # +on_failure+ hears about a catch-up that failed in the background or a
+    # handler that raised after the first catch-up.
+    def initialize(handler, list_after, on_failure)
+      require 'async/semaphore'
+      @handler = handler
+      @list_after = list_after
+      @on_failure = on_failure
+      @last_seq = @catch_ups = 0
+      @started = @closed = false
+      @held = DurableMessageBacklog.new
+      @reads = Async::Semaphore.new(1)
+      @background = DurableMessageCatchUps.new(
+        -> { read_missed }, -> { release_live }, -> { catch_up_in_background }, on_failure
+      )
+    end
+
+    def live(data)
+      held = published(data) unless @closed
+      return unless held
+
+      waiting = behind?
+      @held.hold(held)
+      return if waiting
+      return catch_up_in_background if held.prev_seq > @last_seq
+
+      @background.release
+    end
+
+    # Reads what was missed, then releases the held messages. Raises the
+    # list's or the handler's error, closing the stream before anything held
+    # is delivered, and raises Realtime::ClosedError if the stream was closed
+    # meanwhile. Call it from the task that subscribes, which the catch-ups
+    # the stream starts itself run under. Those start once it has read, so
+    # one asked for while subscribing cannot call the handler before the
+    # read whose errors the subscriber hears.
+    def catch_up
+      begin_catch_up
+      read_missed(first: true)
+      @background.start unless @closed
+      raise Realtime::ClosedError, ENDED if @closed
+    end
+
+    # Reads back what the channel lost, as when it resubscribes or had no room
+    # for a publication. One catch-up waiting its turn reads whatever more are
+    # asked for meanwhile, so a burst of dropped publications reads once.
+    def catch_up_in_background
+      return if @background.pending?
+
+      begin_catch_up
+      @background.request
+    end
+
+    # Not stopped: the handler a catch-up is running may be what closed it.
+    def close
+      @closed = true
+      @held.clear
+      @background.close
+    end
+
+    private
+
+    def behind? = !@started || @catch_ups.positive? || !@held.empty?
+
+    # Delivers the held live messages that follow on from the last one
+    # delivered, until a catch-up is asked for. One left behind a gap is read
+    # back.
+    def release_live
+      while @catch_ups.zero? && (held = @held.take_following(@last_seq))
+        deliver(held.message, report: true)
+      end
+      catch_up_in_background unless @held.empty?
+    end
+
+    # Counted before the read waits its turn, so nothing is delivered live
+    # meanwhile. A catch-up replaces the retry that was waiting.
+    def begin_catch_up
+      @started = true
+      @background.cancel_retry
+      @catch_ups += 1
+    end
+
+    def read_missed(first: false)
+      read = false
+      @reads.acquire do
+        read_pages(report: !first)
+        read = true
+      ensure
+        close if first && !read
+        # Released by the last catch-up only, and while still counted, so a
+        # live message that arrives meanwhile is held behind the released ones.
+        release(read, report: !first) if @catch_ups == 1
+      end
+    ensure
+      @catch_ups -= 1
+    end
+
+    def read_pages(report:)
+      until @closed
+        after = @last_seq
+        page = @list_after.call(after)
+        page.messages.each { |message| deliver(message, report:) }
+        # A page that delivered nothing would be asked for again unchanged.
+        return if !page.has_more || @last_seq == after
+      end
+    end
+
+    # Delivers the held messages that follow on from the last one delivered,
+    # and retries the read while any is left behind a gap or the read failed.
+    def release(read, report:)
+      while (held = @held.take_following(@last_seq))
+        deliver(held.message, report:)
+      end
+    ensure
+      read && @held.empty? ? @background.caught_up : @background.retry_later
+    end
+
+    def deliver(message, report:)
+      call_handler(message, report) unless @closed || message.seq <= @last_seq
+    end
+
+    # Only the first catch-up raises what the handler raised, to the caller
+    # that subscribes. Later the stream's own task would lose it, so it is
+    # reported and delivery goes on.
+    def call_handler(message, report)
+      @last_seq = message.seq
+      @handler.call(message)
+    rescue StandardError => e
+      raise unless report
+
+      @on_failure.call(e)
+    end
+
+    # A publication that does not read as a message is still one the
+    # execution published, so the list is read for it as for a dropped one.
+    def published(data)
+      message = durable_message(data)
+      Held.new(message:, prev_seq: broadcast_prev_seq(data)) if message.direction == 'out'
+    rescue TypeError
+      catch_up_in_background
+      nil
+    end
+  end
+  private_constant :DurableMessageStream
+end

data/lib/volcano/durable_messages.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Messages an execution publishes, delivered to the block #subscribe took
+  # until #unsubscribe.
+  class DurableMessageSubscription
+    # Subscribes +channel+ and delivers what was published so far. Leaves the
+    # channel if that fails, or the task running it is stopped. +session+ can
+    # end the subscription from the first read on.
+    def self.open(session, stream, channel, realtime)
+      subscription = session.end_with(new(stream, channel, realtime))
+      finished = false
+      begin
+        channel.subscribe
+        stream.catch_up
+        finished = true
+      ensure
+        subscription.unsubscribe unless finished
+      end
+      subscription
+    end
+
+    def initialize(stream, channel, realtime)
+      @stream = stream
+      @channel = channel
+      @realtime = realtime
+      channel.on('message') { |data| stream.live(data) }
+    end
+
+    # Stops delivering messages and leaves the execution's channel. Safe to
+    # repeat, and to call from the block.
+    def unsubscribe
+      @stream.close
+      @realtime.__send__(:remove_durable_channel, @channel)
+    end
+
+    # The channel holds the client token and the realtime client the session,
+    # so inspection shows neither.
+    def inspect = '#<Volcano::DurableMessageSubscription>'
+    alias to_s inspect
+
+    def pretty_print(printer) = printer.text(inspect)
+  end
+
+  # Sends to, lists, and follows the messages of durable executions.
+  #
+  # Each method addresses an execution by its function's name or id and the
+  # execution's id. By default they use the application route with the
+  # client's credential, as Durable#start does; pass +client_token:+ where that
+  # credential needs it, as an anon key or a user who did not start the
+  # execution does. Pass +project_id:+ to use the owner's project route with
+  # the session's platform token instead.
+  class DurableMessages
+    include DurableArguments
+    include DurableMessageArguments
+    include DurableMessageResponses
+
+    Target = Data.define(:project_id, :function_id, :execution_id, :client_token)
+
+    # Reopens the generated record to mask its credential.
+    class Target
+      # @dynamic project_id, function_id, execution_id, client_token
+
+      # The client token is a bearer credential, so inspection masks it, as
+      # DurableExecution#inspect does.
+      def inspect
+        fields = to_h.map do |name, value|
+          "#{name}=#{name == :client_token && value ? Redaction::MARKER : value.inspect}"
+        end
+        "#<data #{self.class.name} #{fields.join(', ')}>"
+      end
+
+      def to_s = inspect
+
+      def pretty_print(printer) = printer.text(inspect)
+    end
+    private_constant :Target
+
+    SEND_OPTIONS = %i[idempotency_key client_token project_id].freeze
+    LIST_OPTIONS = %i[direction name after limit client_token project_id].freeze
+    private_constant :SEND_OPTIONS, :LIST_OPTIONS
+
+    def initialize(client, transport, realtime)
+      @client = client
+      @transport = transport
+      @realtime = realtime
+    end
+
+    # Sends a message to a running execution, queued until a wait for its
+    # +name+ takes it. +data+ is any JSON value. The returned message's
+    # +status+ is +delivered+ when a wait took it at once, +delivering+ while
+    # that handover is still being confirmed, and +queued+ otherwise. Sending
+    # again with an +idempotency_key:+ the same sender has used on the
+    # execution returns the message the first send stored, in its current
+    # status, and sends nothing. Sending to an execution that has ended raises
+    # Error::ConflictError, whose +code+ is +execution_not_running+, and to one
+    # holding 100 messages no wait has taken, +too_many_queued_messages+.
+    def send_message(function_name, execution_id, name, data = nil, **options)
+      target = message_target(function_name, execution_id, known_options(options, SEND_OPTIONS))
+      name = message_name(name)
+      key = bounded_text(options[:idempotency_key], 'idempotency_key', MAX_IDEMPOTENCY_KEY_LENGTH)
+      response = Transport.invoke do
+        @transport.send_durable_message(
+          authorization: authorization(target), target: target, name: name,
+          data: ImmutableRequestValue.capture(data), idempotency_key: key
+        )
+      end
+      durable_message(Transport.body(response, response.status == 200 ? 200 : 201))
+    end
+
+    # Lists an execution's messages in both directions, oldest first, filtered
+    # by any of +direction+ (+in+ or +out+), +name+, +after+ (a +seq+), and
+    # +limit+ (1 to 500), given as keywords with +client_token+ and
+    # +project_id+. Read the next page with +after+ set to the last message's
+    # +seq+.
+    def list(function_name, execution_id, filters = {})
+      filters = list_filters(filters)
+      target = message_target(function_name, execution_id, filters)
+      durable_message_page(Transport.body(list_messages(target, list_query(filters)), 200))
+    end
+
+    # Delivers every message the execution publishes to the block, in order,
+    # once each, and one call at a time. Messages it published before the
+    # call come first, and after a reconnect the ones published meanwhile are
+    # read back before live delivery resumes, over the owner's route when
+    # +project_id+ is given. Returns a
+    # DurableMessageSubscription once the messages published so far are
+    # delivered; a block that raises meanwhile ends the subscription and
+    # raises here, and a subscription ended meanwhile raises
+    # Realtime::ClosedError.
+    #
+    # Follows the execution on the client's realtime connection, so call it
+    # inside that connection's Async reactor, with a signed-in session. A
+    # connection an earlier session opened is closed, raising
+    # Error::SessionChangedError. A catch-up that fails in the background is
+    # reported to Realtime#on_error and retried, backing off to every 30
+    # seconds; a block that raises later is reported there too, and delivery
+    # goes on. Realtime#remove_all_channels and Realtime#disconnect end the
+    # subscription, and so does signing out, signing in again, or setting
+    # another session, though not a token refresh, and a reconnect the server
+    # refuses to restore the subscription on for good, which is reported to
+    # Realtime#on_error once. Raises
+    # Realtime::DuplicateSubscriptionError when this client already follows the
+    # execution.
+    def subscribe(function_name, execution_id, client_token: nil, project_id: nil, &handler)
+      raise ArgumentError, 'subscribe requires a block' unless block_given?
+
+      target = message_target(function_name, execution_id, { client_token: client_token, project_id: project_id })
+      session = DurableMessageSession.new(@realtime)
+      stream = session.stream(handler, reader(target), failure_reporter)
+      DurableMessageSubscription.open(session, stream, durable_channel(target, session), @realtime)
+    end
+
+    private
+
+    def durable_channel(target, session)
+      @realtime.__send__(:durable_channel, target.execution_id, target.client_token, session) ||
+        raise(Realtime::DuplicateSubscriptionError, 'already subscribed to this execution; unsubscribe first')
+    end
+
+    # Reads off the reactor, which the transport would block along with the
+    # connection's reads and heartbeats.
+    def reader(target)
+      lambda do |after|
+        authorization = authorization(target)
+        response = @realtime.__send__(:blocking) do
+          list_messages(target, { direction: 'out', after: after }, authorization)
+        end
+        durable_message_page(Transport.body(response, 200))
+      end
+    end
+
+    def list_messages(target, query, authorization = authorization(target))
+      Transport.invoke do
+        @transport.list_durable_messages(authorization: authorization, target: target, query: query)
+      end
+    end
+
+    def failure_reporter
+      ->(error) { @realtime.__send__(:report_channel_error, error) }
+    end
+
+    def authorization(target)
+      target.project_id ? @client.session_token : @client.function_token
+    end
+
+    def message_target(function_name, execution_id, options)
+      project_id = options[:project_id]
+      Target.new(
+        project_id: project_id.nil? ? nil : identifier(project_id, 'project_id'),
+        function_id: identifier(function_name, 'function_name'),
+        execution_id: identifier(execution_id, 'execution_id'),
+        client_token: bounded_text(options[:client_token], 'client_token', MAX_CLIENT_TOKEN_LENGTH)
+      )
+    end
+
+    def list_filters(filters)
+      raise TypeError, 'filters must be a Hash' unless filters.is_a?(Hash)
+
+      known_options(filters, LIST_OPTIONS)
+    end
+
+    def list_query(filters)
+      name = filters[:name]
+      {
+        direction: direction_filter(filters[:direction]), name: name.nil? ? nil : message_name(name),
+        after: after_argument(filters[:after]), limit: limit_argument(filters[:limit])
+      }.compact
+    end
+
+    def direction_filter(value)
+      return if value.nil?
+
+      DIRECTIONS.find { |direction| direction == value.to_s } || raise(ArgumentError, "direction must be 'in' or 'out'")
+    end
+  end
+end

data/lib/volcano/durable_models.rb

@@ -5,7 +5,7 @@ require_relative 'immutable_request_value'
 
 module Volcano
   DURABLE_EXECUTION_ATTRIBUTES = %i[
-    id function_id name status region created_at result result_expired error completed_at
+    id function_id name status region created_at result result_expired error completed_at client_token
   ].freeze
   private_constant :DURABLE_EXECUTION_ATTRIBUTES
 
@@ -35,6 +35,10 @@ module Volcano
   # once its retention lapses. That is not the same as a function that returned
   # nothing, so read `result_expired` before concluding anything from a missing
   # result.
+  #
+  # `client_token` lets a browser, or a user who did not start the execution,
+  # reach its messages. Only the start that created the execution returns it;
+  # a repeat under the same name and every read leave it nil.
   DurableExecution = Data.define(*DURABLE_EXECUTION_ATTRIBUTES)
 
   # Reopens the generated record for checked initialization.
@@ -58,6 +62,17 @@ module Volcano
       DURABLE_TERMINAL_STATUSES.include?(status)
     end
 
+    # The client token is a bearer credential, so inspection masks it.
+    def inspect
+      fields = to_h.map do |name, value|
+        "#{name}=#{name == :client_token && value ? Redaction::MARKER : value.inspect}"
+      end
+      "#<data #{self.class.name} #{fields.join(', ')}>"
+    end
+    alias to_s inspect
+
+    def pretty_print(printer) = printer.text(inspect)
+
     private
 
     # `result` is the function's own JSON, so it is frozen all the way down.
@@ -92,15 +107,29 @@ module Volcano
 
     def durable_execution(payload)
       values = execution_payload(payload)
+      result, result_expired, error, completed_at = execution_outcome(values)
       DurableExecution.new(
         id: execution_text(values, 'id'), function_id: execution_text(values, 'function_id'),
         name: execution_text(values, 'name'), status: execution_text(values, 'status'),
         region: execution_text(values, 'region'), created_at: execution_time(values),
-        result: execution_result(values['result']), result_expired: execution_expired(values['result_expired']),
-        error: execution_error(values['error']), completed_at: parse_time(values['completed_at'])
+        result: result, result_expired: result_expired, error: error, completed_at: completed_at,
+        client_token: client_token(values['client_token'])
       )
     end
 
+    def execution_outcome(values)
+      [
+        execution_result(values['result']), execution_expired(values['result_expired']),
+        execution_error(values['error']), parse_time(values['completed_at'])
+      ]
+    end
+
+    def client_token(value)
+      return value if value.nil? || (value.is_a?(String) && !value.empty?)
+
+      raise TypeError, INCOMPLETE_EXECUTION
+    end
+
     def execution_payload(payload)
       raise TypeError, INCOMPLETE_EXECUTION unless payload.is_a?(Hash)
 
@@ -165,10 +194,6 @@ module Volcano
       value
     end
 
-    def present_string?(value)
-      value.is_a?(String) && !value.strip.empty?
-    end
-
     def parse_time(value)
       return Time.iso8601(value) if value.is_a?(String)
       return value if value.nil? || value.is_a?(Time)

data/lib/volcano/errors.rb

@@ -16,6 +16,11 @@ module Volcano
     end
 
     class AuthenticationError < VolcanoError; end
+
+    # Raised for HTTP 403: the credential is valid but may not do this. It
+    # remains an AuthenticationError so existing handlers still catch it.
+    class PermissionDeniedError < AuthenticationError; end
+
     class ValidationError < VolcanoError; end
     class NotFoundError < VolcanoError; end
     class ConflictError < VolcanoError; end

data/lib/volcano/generated/lib/volcano-generated/api/anon_keys_api.rb

@@ -1,7 +1,7 @@
 =begin
-#Volcano Hosting API
+#Volcano API
 
-#Public API for Volcano Hosting clients, SDKs, and CLI tooling (Port 8000).  This specification intentionally excludes first-party/internal APIs. See api/openapi-internal.yaml for non-public internal and Builder operations.
+#Public API for Volcano clients, SDKs, and CLI tooling (Port 8000).  This specification intentionally excludes first-party/internal APIs. See api/openapi-internal.yaml for non-public internal and Builder operations.
 
 The version of the OpenAPI document: 3.0.0
 Contact: support@volcano.dev
@@ -72,7 +72,7 @@ module Volcano::Generated
       return_type = opts[:debug_return_type] || 'AnonKey'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || ['UserToken']
+      auth_names = opts[:debug_auth_names] || ['UserToken', 'ProjectAccessToken']
 
       new_options = opts.merge(
         :operation => :"AnonKeysApi.create_anon_key",
@@ -141,7 +141,7 @@ module Volcano::Generated
       return_type = opts[:debug_return_type] || 'AnonKey'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || ['UserToken']
+      auth_names = opts[:debug_auth_names] || ['UserToken', 'ProjectAccessToken']
 
       new_options = opts.merge(
         :operation => :"AnonKeysApi.get_anon_key",
@@ -242,7 +242,7 @@ module Volcano::Generated
       return_type = opts[:debug_return_type] || 'ListAnonKeys200Response'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || ['UserToken']
+      auth_names = opts[:debug_auth_names] || ['UserToken', 'ProjectAccessToken']
 
       new_options = opts.merge(
         :operation => :"AnonKeysApi.list_anon_keys",
@@ -311,7 +311,7 @@ module Volcano::Generated
       return_type = opts[:debug_return_type] || 'AnonKey'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || ['UserToken']
+      auth_names = opts[:debug_auth_names] || ['UserToken', 'ProjectAccessToken']
 
       new_options = opts.merge(
         :operation => :"AnonKeysApi.regenerate_anon_key",
@@ -380,7 +380,7 @@ module Volcano::Generated
       return_type = opts[:debug_return_type]
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || ['UserToken']
+      auth_names = opts[:debug_auth_names] || ['UserToken', 'ProjectAccessToken']
 
       new_options = opts.merge(
         :operation => :"AnonKeysApi.revoke_anon_key",
@@ -449,7 +449,7 @@ module Volcano::Generated
       return_type = opts[:debug_return_type] || 'AnonKey'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || ['UserToken']
+      auth_names = opts[:debug_auth_names] || ['UserToken', 'ProjectAccessToken']
 
       new_options = opts.merge(
         :operation => :"AnonKeysApi.set_default_anon_key",