volcano-sdk 0.32.7 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b611d95fd4b7fb342a631e1c1ffe7c8dd42c9327556dfd01d64ad0f971e4d475
-  data.tar.gz: 549dabf87e25ee1fdea58c13573d1fb03e7b58ffd153c227c8fb7223247171a8
+  metadata.gz: e228fb6138aee4fa4f6bce0f810386d08c3023ed23b3b98ccaf733ba9f1921a6
+  data.tar.gz: df06c47b64ac87c6d44a7a110d7355ea41fe25354aef328cfdd8b246a1375307
 SHA512:
-  metadata.gz: 304e984a96c2af8898412fd3def954476c5f9bc406832ff581139eac80776f92552357bae744266c9248e9d84a317e2dd533edb8a48612eabee5f86283921305
-  data.tar.gz: 8beff771c0a4294ce05f0c95e3e43bbf915781d34ee2d3284fae81a8a2f8eda0509e7092136a324cee91e643ce75e2768f7f9f01fc3f936668f90a9025101fe8
+  metadata.gz: 1fd53ec98301db0ea75e0e947558664be0fd04a10982279d7eaf71c90f15493d7205c086cd7c11d7038d25d1c68e953fe26253f58fb4cc44df08a72b81968636
+  data.tar.gz: 77a02c19da00001b7103e300dc4666f2ac2f1fa339bcc28dd87782d5a4965729b4bd1d67c9486da5a6ed14c4b24b5a93efdaf1feb2010a55a44af5edeadadd51

data/README.md

@@ -1,6 +1,6 @@
 # Volcano Ruby SDK
 
-Official Ruby SDK for Volcano. Requires Ruby 3.2 or later.
+Official Ruby SDK for Volcano. Requires Ruby 3.3 or later.
 
 Start with the [Ruby quickstart](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md).
 
@@ -550,6 +550,57 @@ caller needs.
 Ruby remains a fully supported runtime for [standard
 functions](https://volcano.dev/platform/functions/overview).
 
+### Decide durable approvals
+
+A durable function written in JavaScript or Python can pause until a person
+approves or denies a request. Ruby lists those requests and decides them:
+
+```ruby
+approvals = owner_client.durable.approvals
+
+page = approvals.list(project_id, status: "pending", function: "refunds", limit: 20)
+page.approvals.each do |approval|
+  puts [approval.id, approval.title, approval.details, approval.expires_at]
+end
+
+begin
+  approval = approvals.approve(project_id, page.approvals.first.id, comment: "Matches the invoice")
+  puts approval.decision.decided_at
+rescue Volcano::Error::ConflictError => e
+  puts e.code # approval_decided, approval_expired, or approval_cancelled
+end
+
+approvals.deny(project_id, "00000000-0000-4000-8000-000000000051")
+
+stats = approvals.stats(project_id, from: Time.now - (7 * 86_400))
+puts [stats.counts.pending, stats.approval_rate, stats.median_seconds_to_decision]
+```
+
+`list` returns the newest approvals first. Filter by `status` (`pending`,
+`approved`, `denied`, `expired`, or `cancelled`), `function` (a durable
+function's id or name), `execution_id`, and a `from`/`to` window given as a
+`Time` or an ISO 8601 string with an offset, such as `2026-10-01T00:00:00Z`.
+`stats` covers the last 30 days unless you pass a
+window, up to 366 days. It counts approvals by status, gives the approval rate
+and the median and 90th-percentile time to a decision (nil when nothing in the
+window was decided), lists the ten functions that requested the most approvals
+with the rest summed in `other_functions`, and returns `daily` counts keyed by
+`YYYY-MM-DD` UTC dates, omitting days without approvals.
+
+An approval keeps its function and execution names after they are deleted;
+their ids become nil. `decision` is nil unless the approval was approved or
+denied, and its `decided_by` is nil once the deciding account is deleted.
+
+Reading approvals accepts the project owner's platform user token or a project
+access token. Approving and denying require a person: a project access token
+raises `Volcano::Error::PermissionDeniedError` (HTTP 403, a subclass of
+`AuthenticationError`, so existing rescues still apply). Repeating the same
+decision returns the approval unchanged; a conflicting decision, or deciding an
+expired or cancelled approval, raises `Volcano::Error::ConflictError` (HTTP
+409). An unknown approval, or one in another project, raises
+`Volcano::Error::NotFoundError`. A `comment` is optional, up to 2,000
+characters.
+
 ### Read project logs
 
 ```ruby
@@ -881,7 +932,7 @@ delivery.
 
 ## Dependencies
 
-Installing `volcano-sdk` pulls in eight gems, plus their own transitive
+Installing `volcano-sdk` pulls in nine gems, plus their own transitive
 dependencies:
 
 | Gem                                                          | Why                                                                     |
@@ -892,6 +943,7 @@ dependencies:
 | [`async-http`](https://rubygems.org/gems/async-http)         | The endpoint realtime dials                                             |
 | [`async-websocket`](https://rubygems.org/gems/async-websocket) | The realtime transport itself                                         |
 | [`protocol-rack`](https://rubygems.org/gems/protocol-rack)   | A requirement of `async-websocket`, pinned here so the version is ours  |
+| [`io-event`](https://rubygems.org/gems/io-event)             | The event loop under `async`, with a floor at the release that fixes AIKIDO-2026-10943 |
 | [`base64`](https://rubygems.org/gems/base64)                 | Required by the generated client, and no longer a default gem since Ruby 3.4 |
 | [`json`](https://rubygems.org/gems/json)                     | Request and response encoding for the generated client                  |
 

data/lib/volcano/auth_profile_fields.rb

@@ -80,8 +80,8 @@ module Volcano
 
     def profile_optional_boolean(value)
       return if value.nil?
-      return true if value == true
-      return false if value == false
+      return true if value.equal?(true)
+      return false if value.equal?(false)
 
       raise Error::AuthenticationError, INVALID_USER
     end

data/lib/volcano/client.rb

@@ -16,9 +16,9 @@ module Volcano
     end
     private_constant :SessionToken
 
-    attr_reader :auth, :functions, :durable, :logs, :storage, :locks, :realtime
+    attr_reader :sandboxes, :auth, :functions, :durable, :logs, :storage, :locks, :realtime
 
-    # @dynamic auth, functions, durable, logs, storage, locks, realtime
+    # @dynamic sandboxes, auth, functions, durable, logs, storage, locks, realtime
 
     def initialize( # rubocop:disable Metrics/ParameterLists -- Preserve typed constructor keywords.
       anon_key:,
@@ -122,6 +122,7 @@ module Volcano
       @logs = Logs.new(self, @transport)
       @storage = Storage.new(self, @transport, api_url: @api_url, anon_key: @anon_key)
       @locks = Locks.new(self, @transport)
+      @sandboxes = Sandboxes.new(self, @transport)
       @realtime = Realtime.new(
         self,
         api_url: @api_url,

data/lib/volcano/durable.rb

@@ -3,16 +3,19 @@
 module Volcano
   # Starts and follows executions of deployed durable functions.
   class Durable
-    # What the platform accepts as an execution name, and the page size it
-    # serves at most. Mirrored from the wire contract so a refusal is the
-    # facade's rather than the generated client's.
+    # What the platform accepts as an execution name. Mirrored from the wire
+    # contract so a refusal is the facade's rather than the generated client's.
     EXECUTION_NAME = /\A[A-Za-z0-9._-]{1,255}\z/
-    MAX_PAGE_SIZE = 100
+    include DurableArguments
     include DurableResponses
 
+    # Lists, reads, and decides the approvals durable workflows request.
+    attr_reader :approvals
+
     def initialize(client, transport)
       @client = client
       @transport = transport
+      @approvals = DurableApprovals.new(client, transport)
     end
 
     # Starts an execution and returns its handle. A durable function is never
@@ -99,18 +102,6 @@ module Volcano
       ]
     end
 
-    # An empty path segment would address the collection instead of the
-    # execution, 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) && present_string?(value)
-
-      value.strip.freeze
-    end
-
-    # The generated client validates this header against the same pattern and
-    # raises its own message, naming the operation and the option key it knows
-    # the header by. Checked here first so the caller reads a message about the
-    # argument they passed, the way Functions#invoke does for a function name.
     def execution_name_argument(value)
       name = identifier(value, 'execution_name')
       unless EXECUTION_NAME.match?(name)
@@ -120,23 +111,5 @@ module Volcano
 
       name
     end
-
-    # Same reason: the generated client enforces the page and limit bounds and
-    # answers with its own vocabulary.
-    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
   end
 end

data/lib/volcano/durable_approval_models.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative 'immutable_request_value'
+
+module Volcano
+  DURABLE_APPROVAL_ATTRIBUTES = %i[
+    id status name title description details function execution requested_at expires_at decision
+  ].freeze
+  DURABLE_APPROVAL_STATS_ATTRIBUTES = %i[
+    from to counts approval_rate median_seconds_to_decision p90_seconds_to_decision
+    functions other_functions daily
+  ].freeze
+  private_constant :DURABLE_APPROVAL_ATTRIBUTES, :DURABLE_APPROVAL_STATS_ATTRIBUTES
+
+  # Checks keywords for the approval records with too many fields for an
+  # explicit keyword list, and owns immutable copies of their values.
+  module DurableApprovalAttributes
+    def self.capture(attributes, names, optional:)
+      unknown = attributes.keys - names
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      missing = names - optional - attributes.keys
+      raise ArgumentError, "missing keywords: #{missing.join(', ')}" unless missing.empty?
+
+      names.to_h { |name| [name, immutable_value(attributes[name])] }
+    end
+
+    def self.immutable_value(value)
+      case value
+      when Hash, Array, Time, String then ImmutableRequestValue.capture(value)
+      else value
+      end
+    end
+  end
+  private_constant :DurableApprovalAttributes
+
+  # The durable function that requested an approval. `id` is nil once the
+  # function has been deleted; `name` is kept.
+  DurableApprovalFunction = Data.define(:id, :name)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalFunction
+    # @dynamic id, name, members, with, to_h, deconstruct, deconstruct_keys, self.[]
+    # @dynamic self.members
+    def initialize(id:, name:)
+      id = id&.dup&.freeze
+      name = name.dup.freeze
+      super
+    end
+  end
+
+  # The durable execution that requested an approval. `id` and `status` are
+  # nil once the execution is no longer retained; `name` is kept.
+  DurableApprovalExecution = Data.define(:id, :name, :status)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalExecution
+    # @dynamic id, name, status, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
+    def initialize(id:, name:, status:)
+      id = id&.dup&.freeze
+      name = name.dup.freeze
+      status = status&.dup&.freeze
+      super
+    end
+  end
+
+  # The person who decided an approval.
+  DurableApprovalDecider = Data.define(:id, :email)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalDecider
+    # @dynamic id, email, members, with, to_h, deconstruct, deconstruct_keys, self.[]
+    # @dynamic self.members
+    def initialize(id:, email:)
+      id = id.dup.freeze
+      email = email.dup.freeze
+      super
+    end
+  end
+
+  # Who decided an approval and when. `decided_by` is nil once that person's
+  # account is deleted.
+  DurableApprovalDecision = Data.define(:comment, :decided_by, :decided_at)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalDecision
+    # @dynamic comment, decided_by, decided_at, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
+    def initialize(comment:, decided_by:, decided_at:)
+      comment = comment.dup.freeze
+      decided_at = decided_at.dup.freeze
+      super
+    end
+  end
+
+  # An approval a durable workflow requested.
+  #
+  # `decision` is nil unless the approval was approved or denied, and
+  # `expires_at` is nil when the workflow set no timeout. `details` is the
+  # workflow's own JSON, frozen all the way down.
+  DurableApproval = Data.define(*DURABLE_APPROVAL_ATTRIBUTES)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApproval
+    # @dynamic id, status, name, title, description, details, function, execution
+    # @dynamic requested_at, expires_at, decision, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
+    def initialize(**attributes)
+      values = DurableApprovalAttributes.capture(
+        attributes, DURABLE_APPROVAL_ATTRIBUTES, optional: %i[details expires_at decision]
+      )
+      attributes = values
+      super
+    end
+  end
+
+  # One page of a project's approvals, newest first.
+  DurableApprovalPage = Data.define(:approvals, :page, :limit, :total, :has_more)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalPage
+    # @dynamic approvals, page, limit, total, has_more, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
+    def initialize(approvals:, page:, limit:, total:, has_more:)
+      approvals = approvals.to_a.dup.freeze
+      super
+    end
+  end
+
+  # Approvals by status. `requested` counts every approval, whatever its status.
+  DurableApprovalCounts = Data.define(:requested, :pending, :approved, :denied, :expired, :cancelled)
+
+  # One workflow's approval counts.
+  DurableApprovalFunctionCounts = Data.define(:function, :counts)
+
+  # Approval counts for one UTC day, given as `YYYY-MM-DD`.
+  DurableApprovalDailyCounts = Data.define(:date, :counts)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalDailyCounts
+    # @dynamic date, counts, members, with, to_h, deconstruct, deconstruct_keys, self.[]
+    # @dynamic self.members
+    def initialize(date:, counts:)
+      date = date.dup.freeze
+      super
+    end
+  end
+
+  # Approval outcomes over a time window.
+  #
+  # `functions` holds the ten workflows that requested the most approvals and
+  # `other_functions` sums the rest. `daily` omits days without approvals.
+  # The rate and decision times are nil when nothing in the window was decided.
+  DurableApprovalStats = Data.define(*DURABLE_APPROVAL_STATS_ATTRIBUTES)
+
+  # Reopens the generated record for checked initialization.
+  class DurableApprovalStats
+    # @dynamic from, to, counts, approval_rate, median_seconds_to_decision
+    # @dynamic p90_seconds_to_decision, functions, other_functions, daily, members, with
+    # @dynamic to_h, deconstruct, deconstruct_keys, self.[], self.members
+    def initialize(**attributes)
+      values = DurableApprovalAttributes.capture(
+        attributes, DURABLE_APPROVAL_STATS_ATTRIBUTES,
+        optional: %i[approval_rate median_seconds_to_decision p90_seconds_to_decision]
+      )
+      attributes = values
+      super
+    end
+  end
+end

data/lib/volcano/durable_approval_responses.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Checks the fields shared by approval and statistics payloads.
+  module DurableApprovalFields
+    INCOMPLETE_APPROVAL = 'Expected a complete durable approval'
+    INCOMPLETE_PAGE = 'Expected a complete durable approval page'
+    INCOMPLETE_STATS = 'Expected complete durable approval statistics'
+    private_constant :INCOMPLETE_APPROVAL, :INCOMPLETE_PAGE, :INCOMPLETE_STATS
+
+    private
+
+    def approval_function(payload, message)
+      values = approval_object(payload, message)
+      DurableApprovalFunction.new(
+        id: optional_approval_text(values['id'], message), name: approval_text(values['name'], message)
+      )
+    end
+
+    def approval_object(payload, message)
+      raise TypeError, message unless payload.is_a?(Hash)
+
+      payload
+    end
+
+    def approval_list(value)
+      raise TypeError, INCOMPLETE_STATS unless value.is_a?(Array)
+
+      value
+    end
+
+    def approval_text(value, message = INCOMPLETE_APPROVAL)
+      raise TypeError, message unless value.is_a?(String) && !value.strip.empty?
+
+      value
+    end
+
+    def optional_approval_text(value, message)
+      value.nil? ? nil : approval_text(value, message)
+    end
+
+    def approval_string(value, message)
+      raise TypeError, message unless value.is_a?(String)
+
+      value
+    end
+
+    def approval_time(value, message)
+      case value
+      when String then Time.iso8601(value)
+      when Time then value
+      else raise TypeError, message
+      end
+    rescue ArgumentError
+      raise TypeError, message, cause: nil
+    end
+
+    def approval_count(value, message = INCOMPLETE_STATS)
+      raise TypeError, message unless value.is_a?(Integer)
+
+      value
+    end
+
+    def approval_flag(value)
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      raise TypeError, INCOMPLETE_PAGE
+    end
+
+    def approval_number(value)
+      case value
+      when nil then nil
+      when Integer, Float then Float(value)
+      else raise TypeError, INCOMPLETE_STATS
+      end
+    end
+  end
+  private_constant :DurableApprovalFields
+
+  # Builds approvals and approval pages from transport payloads.
+  module DurableApprovalResponses
+    include DurableApprovalFields
+
+    private
+
+    def durable_approval(payload)
+      values = approval_object(payload, INCOMPLETE_APPROVAL)
+      id, status, name, title = approval_labels(values)
+      requested_at, expires_at = approval_schedule(values)
+      DurableApproval.new(
+        id: id, status: status, name: name, title: title,
+        description: approval_string(values['description'], INCOMPLETE_APPROVAL),
+        details: approval_details(values['details']),
+        function: approval_function(values['function'], INCOMPLETE_APPROVAL),
+        execution: approval_execution(values['execution']), requested_at: requested_at, expires_at: expires_at,
+        decision: approval_decision(values['decision'])
+      )
+    end
+
+    def durable_approval_page(payload)
+      values = approval_object(payload, INCOMPLETE_PAGE)
+      data = values['data']
+      raise TypeError, INCOMPLETE_PAGE unless data.is_a?(Array)
+
+      DurableApprovalPage.new(
+        approvals: data.map { |entry| durable_approval(entry) }, has_more: approval_flag(values['has_more']),
+        page: approval_count(values['page'], INCOMPLETE_PAGE), limit: approval_count(values['limit'], INCOMPLETE_PAGE),
+        total: approval_count(values['total'], INCOMPLETE_PAGE)
+      )
+    end
+
+    def approval_labels(values)
+      [approval_text(values['id']), approval_text(values['status']),
+       approval_text(values['name']), approval_text(values['title'])]
+    end
+
+    def approval_schedule(values)
+      expires_at = values['expires_at']
+      [approval_time(values['requested_at'], INCOMPLETE_APPROVAL),
+       expires_at.nil? ? nil : approval_time(expires_at, INCOMPLETE_APPROVAL)]
+    end
+
+    def approval_execution(payload)
+      values = approval_object(payload, INCOMPLETE_APPROVAL)
+      DurableApprovalExecution.new(
+        id: optional_approval_text(values['id'], INCOMPLETE_APPROVAL), name: approval_text(values['name']),
+        status: optional_approval_text(values['status'], INCOMPLETE_APPROVAL)
+      )
+    end
+
+    def approval_decision(payload)
+      return if payload.nil?
+
+      values = approval_object(payload, INCOMPLETE_APPROVAL)
+      DurableApprovalDecision.new(
+        comment: approval_string(values['comment'], INCOMPLETE_APPROVAL),
+        decided_by: approval_decider(values['decided_by']),
+        decided_at: approval_time(values['decided_at'], INCOMPLETE_APPROVAL)
+      )
+    end
+
+    def approval_decider(payload)
+      return if payload.nil?
+
+      values = approval_object(payload, INCOMPLETE_APPROVAL)
+      DurableApprovalDecider.new(
+        id: approval_text(values['id']), email: approval_string(values['email'], INCOMPLETE_APPROVAL)
+      )
+    end
+
+    def approval_details(value)
+      Transport.json_value(value)
+    rescue TypeError
+      raise TypeError, INCOMPLETE_APPROVAL, cause: nil
+    end
+  end
+  private_constant :DurableApprovalResponses
+
+  # Builds approval statistics from transport payloads.
+  module DurableApprovalStatsResponses
+    include DurableApprovalFields
+
+    DAY = /\A\d{4}-\d{2}-\d{2}\z/
+    private_constant :DAY
+
+    private
+
+    def durable_approval_stats(payload)
+      values = approval_object(payload, INCOMPLETE_STATS)
+      from, to = approval_window(values)
+      rate, median, p90 = approval_timings(values)
+      functions, daily = approval_breakdown(values)
+      DurableApprovalStats.new(
+        from: from, to: to, counts: approval_counts(values['counts']), approval_rate: rate,
+        median_seconds_to_decision: median, p90_seconds_to_decision: p90, functions: functions,
+        other_functions: approval_counts(values['other_functions']), daily: daily
+      )
+    end
+
+    def approval_window(values)
+      [approval_time(values['from'], INCOMPLETE_STATS), approval_time(values['to'], INCOMPLETE_STATS)]
+    end
+
+    def approval_timings(values)
+      [approval_number(values['approval_rate']), approval_number(values['median_seconds_to_decision']),
+       approval_number(values['p90_seconds_to_decision'])]
+    end
+
+    def approval_breakdown(values)
+      [approval_list(values['functions']).map { |entry| approval_function_counts(entry) },
+       approval_list(values['daily']).map { |entry| approval_daily_counts(entry) }]
+    end
+
+    def approval_counts(payload)
+      values = approval_object(payload, INCOMPLETE_STATS)
+      DurableApprovalCounts.new(
+        requested: approval_count(values['requested']), pending: approval_count(values['pending']),
+        approved: approval_count(values['approved']), denied: approval_count(values['denied']),
+        expired: approval_count(values['expired']), cancelled: approval_count(values['cancelled'])
+      )
+    end
+
+    def approval_function_counts(payload)
+      values = approval_object(payload, INCOMPLETE_STATS)
+      DurableApprovalFunctionCounts.new(
+        function: approval_function(values['function'], INCOMPLETE_STATS), counts: approval_counts(values['counts'])
+      )
+    end
+
+    def approval_daily_counts(payload)
+      values = approval_object(payload, INCOMPLETE_STATS)
+      date = approval_text(values['date'], INCOMPLETE_STATS)
+      valid = DAY.match?(date) && approval_time("#{date}T00:00:00Z", INCOMPLETE_STATS).strftime('%F') == date
+      raise TypeError, INCOMPLETE_STATS unless valid
+
+      DurableApprovalDailyCounts.new(date: date, counts: approval_counts(values['counts']))
+    end
+  end
+  private_constant :DurableApprovalStatsResponses
+end