volcano-sdk 0.33.0 → 0.35.0

data/lib/volcano/durable_approvals.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Lists, reads, and decides the approvals durable workflows request.
+  #
+  # Every operation takes the project id and the client's platform token.
+  # Reads also accept a project access token, including a read-only one.
+  # Deciding takes a person: a project access token is refused with
+  # Error::PermissionDeniedError.
+  class DurableApprovals
+    include DurableArguments
+    include DurableApprovalResponses
+    include DurableApprovalStatsResponses
+
+    # Bounds mirrored from the wire contract, for the reason DurableArguments gives.
+    MAX_FUNCTION_LENGTH = 255
+    MAX_COMMENT_LENGTH = 2000
+
+    def initialize(client, transport)
+      @client = client
+      @transport = transport
+    end
+
+    LIST_FILTERS = %i[status function execution_id from to page limit].freeze
+    private_constant :LIST_FILTERS
+
+    # Lists approvals, newest first, filtered by any of +status+, +function+,
+    # +execution_id+, +from+, +to+, +page+, and +limit+, given as keywords.
+    # +function+ is a durable function's id or name; a name also matches
+    # approvals from a deleted function of that name. +from+ is inclusive and
+    # +to+ exclusive, each a Time or an ISO 8601 string with an offset.
+    def list(project_id, filters = {})
+      project = identifier(project_id, 'project_id')
+      options = list_options(filters)
+      response = Transport.invoke do
+        @transport.list_durable_approvals(authorization: @client.session_token, project_id: project, options: options)
+      end
+      durable_approval_page(Transport.body(response, 200))
+    end
+
+    def get(project_id, approval_id)
+      project = identifier(project_id, 'project_id')
+      approval = identifier(approval_id, 'approval_id')
+      response = Transport.invoke do
+        @transport.get_durable_approval(
+          authorization: @client.session_token, project_id: project, approval_id: approval
+        )
+      end
+      durable_approval(Transport.body(response, 200))
+    end
+
+    # Counts approvals by outcome, overall, per workflow, and per UTC day of
+    # request. The window defaults to the 30 days before +to+, which defaults
+    # to now, and covers at most 366 days.
+    def stats(project_id, function: nil, from: nil, to: nil)
+      project = identifier(project_id, 'project_id')
+      options = window(function, from, to).compact
+      response = Transport.invoke do
+        @transport.get_durable_approval_stats(
+          authorization: @client.session_token, project_id: project, options: options
+        )
+      end
+      durable_approval_stats(Transport.body(response, 200))
+    end
+
+    # Approves a pending approval; the workflow resumes with the decision.
+    # Approving again returns the approval unchanged. Deciding one that was
+    # denied, has expired, or was cancelled raises Error::ConflictError, whose
+    # +code+ is +approval_decided+, +approval_expired+, or +approval_cancelled+.
+    def approve(project_id, approval_id, comment: nil)
+      decide(project_id, approval_id, comment) do |token, project, approval, note|
+        @transport.approve_durable_approval(
+          authorization: token, project_id: project, approval_id: approval, comment: note
+        )
+      end
+    end
+
+    # Denies a pending approval. A denial is a value the workflow branches on,
+    # not an error in it. Repeats and conflicts behave as for #approve.
+    def deny(project_id, approval_id, comment: nil)
+      decide(project_id, approval_id, comment) do |token, project, approval, note|
+        @transport.deny_durable_approval(
+          authorization: token, project_id: project, approval_id: approval, comment: note
+        )
+      end
+    end
+
+    private
+
+    def decide(project_id, approval_id, comment)
+      project = identifier(project_id, 'project_id')
+      approval = identifier(approval_id, 'approval_id')
+      note = comment_argument(comment)
+      response = Transport.invoke { yield(@client.session_token, project, approval, note) }
+      durable_approval(Transport.body(response, 200))
+    end
+
+    def list_options(filters)
+      status, function, execution_id, from, to, page, limit = list_filters(filters).values_at(*LIST_FILTERS)
+      validate_paging(page, limit)
+      window(function, from, to).merge(
+        status: optional_identifier(status, 'status'),
+        execution_id: optional_identifier(execution_id, 'execution_id'), page: page, limit: limit
+      ).compact
+    end
+
+    # Refuses a misspelled filter, as an unknown keyword would be.
+    def list_filters(filters)
+      raise TypeError, 'filters must be a Hash' unless filters.is_a?(Hash)
+
+      unknown = filters.keys - LIST_FILTERS
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      filters
+    end
+
+    def window(function, from, to)
+      { function: function_filter(function), from: timestamp_argument(from, 'from'), to: timestamp_argument(to, 'to') }
+    end
+
+    def optional_identifier(value, field)
+      value.nil? ? nil : identifier(value, field)
+    end
+
+    def function_filter(value)
+      return if value.nil?
+
+      name = value.is_a?(String) ? value.strip : ''
+      return name.freeze if !name.empty? && name.length <= MAX_FUNCTION_LENGTH
+
+      raise ArgumentError, "function must be a durable function id or name of 1 to #{MAX_FUNCTION_LENGTH} characters"
+    end
+
+    def comment_argument(value)
+      return if value.nil?
+      return value.dup.freeze if value.is_a?(String) && value.length <= MAX_COMMENT_LENGTH
+
+      raise ArgumentError, "comment must be a String of at most #{MAX_COMMENT_LENGTH} characters"
+    end
+  end
+end

data/lib/volcano/durable_arguments.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Checks durable arguments before the generated client does. It enforces the
+  # same bounds but raises its own message, naming the operation and the option
+  # key it knows the value by; checked here, the caller reads a message about
+  # the argument they passed, the way Functions#invoke does for a function name.
+  module DurableArguments
+    # The page size the platform serves at most, mirrored from the wire contract.
+    MAX_PAGE_SIZE = 100
+    RFC3339_OFFSET = /(?:[Zz]|[+-]\d{2}:\d{2})\z/
+    private_constant :RFC3339_OFFSET
+
+    private
+
+    # An empty path segment would address the collection instead of the
+    # resource, which is a different request rather than a failed one.
+    def identifier(value, field)
+      raise ArgumentError, "#{field} must be a non-empty String" unless value.is_a?(String) && !value.strip.empty?
+
+      value.strip.freeze
+    end
+
+    def validate_paging(page, limit)
+      raise ArgumentError, 'page must be a positive Integer' unless page.nil? || positive_integer?(page)
+
+      validate_page_limit(limit)
+    end
+
+    def validate_page_limit(limit)
+      return if limit.nil? || (limit.is_a?(Integer) && positive_integer?(limit) && limit <= MAX_PAGE_SIZE)
+
+      raise ArgumentError, "limit must be an Integer between 1 and #{MAX_PAGE_SIZE}"
+    end
+
+    def positive_integer?(value)
+      value.is_a?(Integer) && value.positive?
+    end
+
+    # Sent in UTC with nanoseconds, so a bound keeps the caller's precision.
+    def timestamp_argument(value, field)
+      return if value.nil?
+
+      (value.is_a?(Time) ? value : offset_time(value)).getutc.iso8601(9)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "#{field} must be a Time or an ISO 8601 timestamp with an offset", cause: nil
+    end
+
+    # Time.iso8601 reads a string without an offset in the host's time zone.
+    def offset_time(value)
+      raise TypeError unless value.is_a?(String) && RFC3339_OFFSET.match?(value)
+
+      Time.iso8601(value)
+    end
+  end
+  private_constant :DurableArguments
+end

data/lib/volcano/durable_message_arguments.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Checks durable message arguments before the generated client does, for the
+  # reason DurableArguments gives.
+  module DurableMessageArguments
+    MESSAGE_NAME = /\A[ -~]{1,237}\z/
+    HEADER_VALUE = /\A[ -~]+\z/
+    MAX_IDEMPOTENCY_KEY_LENGTH = 255
+    MAX_CLIENT_TOKEN_LENGTH = 128
+    MAX_LIST_LIMIT = 500
+
+    private
+
+    def known_options(options, known)
+      unknown = options.keys - known
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      options
+    end
+
+    def message_name(value)
+      return value.dup.freeze if value.is_a?(String) && MESSAGE_NAME.match?(value)
+
+      raise ArgumentError, 'name must be 1 to 237 printable ASCII characters'
+    end
+
+    # Sent as a header, which carries printable ASCII only.
+    def bounded_text(value, field, limit)
+      return if value.nil?
+      return value.dup.freeze if value.is_a?(String) && HEADER_VALUE.match?(value) && value.length <= limit
+
+      raise ArgumentError, "#{field} must be 1 to #{limit} printable ASCII characters"
+    end
+
+    def after_argument(value)
+      return value if value.nil? || (value.is_a?(Integer) && !value.negative?)
+
+      raise ArgumentError, 'after must be a non-negative Integer'
+    end
+
+    def limit_argument(value)
+      return value if value.nil? || (value.is_a?(Integer) && value.between?(1, MAX_LIST_LIMIT))
+
+      raise ArgumentError, "limit must be an Integer between 1 and #{MAX_LIST_LIMIT}"
+    end
+  end
+  private_constant :DurableMessageArguments
+end

data/lib/volcano/durable_message_backlog.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Volcano
+  # The live messages a durable message stream holds until the ones before
+  # them are delivered. Past LIMIT the oldest is dropped. Each one held after a
+  # dropped one names a predecessor at or past it, so it waits for a read that
+  # lists the dropped one.
+  class DurableMessageBacklog
+    LIMIT = 128
+    private_constant :LIMIT
+
+    def initialize
+      @held = []
+    end
+
+    def empty? = @held.empty?
+
+    def clear = @held.clear
+
+    def hold(held)
+      @held << held
+      @held.delete(oldest) if @held.size > LIMIT
+      nil
+    end
+
+    # Takes the oldest held message if the one its broadcast names as the one
+    # before it is delivered.
+    def take_following(last_seq)
+      held = oldest
+      @held.delete(held) if held && held.prev_seq <= last_seq
+    end
+
+    private
+
+    def oldest = @held.min_by { |candidate| candidate.message.seq }
+  end
+  private_constant :DurableMessageBacklog
+end

data/lib/volcano/durable_message_catch_ups.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Runs a durable message stream's own work one job at a time: the catch-ups
+  # it starts itself, the release of the live messages it holds, and the wait
+  # before retrying a catch-up that failed, half a second doubling to 30
+  # seconds. It runs in a task of its own rather than the realtime
+  # connection's, which a reconnect stops midway.
+  class DurableMessageCatchUps
+    FIRST_RETRY_SECONDS = 0.5
+    MAX_RETRY_SECONDS = 30.0
+    private_constant :FIRST_RETRY_SECONDS, :MAX_RETRY_SECONDS
+
+    # +read+ runs a catch-up that was asked for, +release+ delivers the held
+    # live messages, +due+ asks for a catch-up once a retry's wait is over, and
+    # +on_failure+ hears about a job that failed.
+    def initialize(read, release, due, on_failure)
+      @read = read
+      @release = release
+      @due = due
+      @on_failure = on_failure
+      @backoff = FIRST_RETRY_SECONDS
+      @retry_delay = @task = @wake = nil
+      @pending = @releasing = @closed = false
+    end
+
+    # A transient child of the caller's task, so call it from the task that
+    # subscribes. Stopping that task, as a disconnect stops a realtime
+    # callback's, does not stop a transient child, and one that ends hands it
+    # to its parent.
+    def start
+      @task ||= Async::Task.current.async(transient: true) { work }
+      nil
+    end
+
+    def request
+      @pending = true
+      wake.signal
+      nil
+    end
+
+    def release
+      @releasing = true
+      wake.signal
+      nil
+    end
+
+    # Whether a catch-up asked for has yet to start reading.
+    def pending? = @pending
+
+    def retry_later
+      return if @closed
+
+      @retry_delay = @backoff
+      @backoff = [@backoff * 2, MAX_RETRY_SECONDS].min
+      wake.signal
+      nil
+    end
+
+    def cancel_retry = @retry_delay = nil
+
+    def caught_up = @backoff = FIRST_RETRY_SECONDS
+
+    # Not stopped: the catch-up it is running may be what closed it.
+    def close
+      @closed = true
+      wake.signal
+      nil
+    end
+
+    private
+
+    def work
+      until @closed
+        job = next_job
+        job ? run(job) : await_request
+      end
+    end
+
+    # A catch-up goes first: it releases the held messages itself.
+    def next_job
+      if @pending
+        @pending = false
+        @read
+      elsif @releasing
+        @releasing = false
+        @release
+      end
+    end
+
+    def run(job)
+      job.call
+    rescue StandardError => e
+      @on_failure.call(e)
+    end
+
+    def await_request
+      delay = @retry_delay
+      return wake.wait unless delay
+
+      Async::Task.current.with_timeout(delay) { wake.wait }
+    rescue Async::TimeoutError
+      @due.call
+    end
+
+    def wake
+      require 'async/notification'
+      @wake ||= Async::Notification.new
+    end
+  end
+  private_constant :DurableMessageCatchUps
+end

data/lib/volcano/durable_message_models.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Volcano
+  DURABLE_MESSAGE_ATTRIBUTES = %i[
+    id execution_id direction seq name data sender status sent_at delivered_at
+  ].freeze
+  private_constant :DURABLE_MESSAGE_ATTRIBUTES
+
+  # Who sent a durable message. `type` is the credential it was sent with:
+  # `service_key`, `user`, `anon`, `project` for the owner or a project access
+  # token, or `execution` for a message the execution published. `user_id` is
+  # nil unless `type` is `user`.
+  DurableMessageSender = Data.define(:type, :user_id)
+
+  # Reopens the generated record for checked initialization.
+  class DurableMessageSender
+    # @dynamic type, user_id, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
+    def initialize(type:, user_id: nil)
+      type = type.dup.freeze
+      user_id = user_id&.dup&.freeze
+      super
+    end
+  end
+
+  # A message sent to a durable execution (`direction` `in`), or one it
+  # published (`out`).
+  #
+  # `seq` orders an execution's messages in both directions. It increases with
+  # every message but can skip numbers; list the ones after it with `after:`.
+  # `delivered_at` is nil until the execution receives the message, and for
+  # `out` messages. `data` is frozen all the way down.
+  DurableMessage = Data.define(*DURABLE_MESSAGE_ATTRIBUTES)
+
+  # Reopens the generated record for checked initialization.
+  class DurableMessage
+    # @dynamic id, execution_id, direction, seq, name, data, sender, status, sent_at
+    # @dynamic delivered_at, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
+    def initialize(**attributes)
+      values = DurableApprovalAttributes.capture(
+        attributes, DURABLE_MESSAGE_ATTRIBUTES, optional: %i[data delivered_at]
+      )
+      attributes = values
+      super
+    end
+  end
+
+  # Messages after a `seq`, oldest first. `has_more` says whether more follow;
+  # read them with `after:` set to the last message's `seq`.
+  DurableMessagePage = Data.define(:messages, :has_more)
+
+  # Reopens the generated record for checked initialization.
+  class DurableMessagePage
+    # @dynamic messages, has_more, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
+    def initialize(messages:, has_more:)
+      messages = messages.to_a.dup.freeze
+      super
+    end
+  end
+end

data/lib/volcano/durable_message_responses.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Builds durable messages and message pages from transport payloads.
+  module DurableMessageResponses
+    INCOMPLETE_MESSAGE = 'Expected a complete durable message'
+    INCOMPLETE_PAGE = 'Expected a complete durable message page'
+    DIRECTIONS = %w[in out].freeze
+    private_constant :INCOMPLETE_MESSAGE, :INCOMPLETE_PAGE, :DIRECTIONS
+
+    private
+
+    def durable_message(payload)
+      values = message_object(payload, INCOMPLETE_MESSAGE)
+      id, execution_id, name = message_labels(values)
+      direction, status = message_states(values)
+      DurableMessage.new(
+        id: id, execution_id: execution_id, direction: direction, seq: message_seq(values['seq']), name: name,
+        data: message_data(values['data']), sender: message_sender(values['sender']), status: status,
+        sent_at: message_time(values['sent_at']), delivered_at: optional_message_time(values['delivered_at'])
+      )
+    end
+
+    def message_labels(values)
+      [message_text(values['id']), message_text(values['execution_id']), message_text(values['name'])]
+    end
+
+    # The stream filters on direction, so it has to be one it knows. A status
+    # added later reads as written, as an execution's does.
+    def message_states(values)
+      [message_choice(values['direction'], DIRECTIONS), message_text(values['status'])]
+    end
+
+    # The seq a broadcast says the execution published before it, or 0, naming
+    # no gap, when it has none.
+    def broadcast_prev_seq(payload)
+      prev_seq = message_object(payload, INCOMPLETE_MESSAGE)['prev_seq']
+      prev_seq.is_a?(Integer) ? prev_seq : 0
+    end
+
+    def durable_message_page(payload)
+      values = message_object(payload, INCOMPLETE_PAGE)
+      data = values['data']
+      raise TypeError, INCOMPLETE_PAGE unless data.is_a?(Array)
+
+      messages = data.map { |entry| durable_message(entry) }
+      DurableMessagePage.new(messages: messages, has_more: page_flag(values['has_more']))
+    end
+
+    def page_flag(value)
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      raise TypeError, INCOMPLETE_PAGE
+    end
+
+    def message_object(payload, message)
+      raise TypeError, message unless payload.is_a?(Hash)
+
+      payload
+    end
+
+    def message_text(value)
+      raise TypeError, INCOMPLETE_MESSAGE unless value.is_a?(String) && !value.empty?
+
+      value
+    end
+
+    def message_choice(value, choices)
+      choices.find { |choice| choice == value } || raise(TypeError, INCOMPLETE_MESSAGE)
+    end
+
+    def message_seq(value)
+      raise TypeError, INCOMPLETE_MESSAGE unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    def message_data(value)
+      Transport.json_value(value)
+    rescue TypeError
+      raise TypeError, INCOMPLETE_MESSAGE, cause: nil
+    end
+
+    def message_sender(payload)
+      values = message_object(payload, INCOMPLETE_MESSAGE)
+      user_id = values['user_id']
+      raise TypeError, INCOMPLETE_MESSAGE unless user_id.nil? || user_id.is_a?(String)
+
+      DurableMessageSender.new(type: message_text(values['type']), user_id: user_id)
+    end
+
+    def message_time(value)
+      raise TypeError, INCOMPLETE_MESSAGE unless value.is_a?(String)
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      raise TypeError, INCOMPLETE_MESSAGE, cause: nil
+    end
+
+    def optional_message_time(value)
+      value.nil? ? nil : message_time(value)
+    end
+  end
+  private_constant :DurableMessageResponses
+end

data/lib/volcano/durable_message_session.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Binds a subscription to the session signed in when it opened, as Postgres
+  # delivery does. Signing out, signing in again, or setting another session
+  # ends it; refreshing its token does not. Once ended, the stream reads and
+  # delivers nothing more, rather than another user's messages, and the
+  # subscription leaves the execution's channel.
+  #
+  # It follows the channel for the stream: a reconnect restores the channel
+  # only while the session is the one that subscribed.
+  class DurableMessageSession
+    CHANGED = "The session that subscribed to the execution's messages has changed; " \
+              'the subscription has ended'
+    private_constant :CHANGED
+
+    def initialize(realtime)
+      @realtime = realtime
+      _, @lineage, = realtime.__send__(:capture_session_binding)
+    end
+
+    # A stream that delivers to +handler+ and reads with +list_after+ while
+    # the session is unchanged, and raises Error::SessionChangedError after.
+    def stream(handler, list_after, on_failure)
+      @stream = DurableMessageStream.new(bind(handler), bind_read(list_after), on_failure)
+    end
+
+    # Ends +subscription+ once the session changes. Called before the
+    # subscription subscribes, so before anything checks the session.
+    def end_with(subscription)
+      @subscription = subscription
+    end
+
+    # Asked before a reconnect restores the channel.
+    def restoring = require_session
+
+    # Told when the server refuses to restore the channel for good.
+    def refused = @subscription.unsubscribe
+
+    def resubscribed = @stream.catch_up_in_background
+    def dropped = @stream.catch_up_in_background
+    def close = @stream.close
+
+    private
+
+    def bind(callable)
+      lambda do |argument|
+        require_session
+        callable.call(argument)
+      end
+    end
+
+    # A page read while the session changed is not delivered, even an empty
+    # one, which delivers nothing that would check it.
+    def bind_read(list_after)
+      lambda do |after|
+        require_session
+        list_after.call(after).tap { require_session }
+      end
+    end
+
+    def require_session
+      _, lineage, session = @realtime.__send__(:capture_session_binding)
+      return if session && lineage == @lineage
+
+      @stream.close
+      @subscription.unsubscribe
+      raise Error::SessionChangedError, CHANGED
+    end
+  end
+  private_constant :DurableMessageSession
+end