volcano-sdk 0.9.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4fdce577eb0f97e2359db37774f29986e40c24d7d8b4bf64b67ccca4c96ea85
-  data.tar.gz: 5bb422eb1a068e899aa6de617f2bfc4bf78128698009f384c37254c753ae3ea1
+  metadata.gz: ee82d4e1a777fcbca79d4ac464ae7ad87d8f0374fb6955cd1e61167a9c82641c
+  data.tar.gz: fd76dca669566978d588a0c0eb01c38b17166a621ae43f1a0f44862884083fb8
 SHA512:
-  metadata.gz: b0cd140b083357a515a32e3f0dccbc5280519cbaa6f08f1881f745675b979193dd6bd1ddb9e6b415ac55cdabbdcfda44a1b157e97bc2c9f0f1370292ff377922
-  data.tar.gz: 711a49849712a130ac0da5256bef2297428fd3fa2e69e91853842be89752b0e2406e66dc88c88fea78dea29bdfdfd6146701b4aa6a564638a24dad8c42904aab
+  metadata.gz: 4ce4ffb6d72500cfaae2736bede0a7438a1bf079a3c5c2e540ebf3bd737eb2157c46c8e08011b4d93a15deb900daf616fe076c64f3e29c3dfc0c08ba2e80acce
+  data.tar.gz: 8486d6ae8e2fb766e918610389ca94eb98d08446d01a5beebb7002b5a44448508a31681da6100a59ab5f62d4d5b0894fca9072ae09a33914d0c45f9d24f32f03

data/README.md

@@ -495,6 +495,55 @@ Anonymous and service keys do not refresh.
 
 See the [functions guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/functions.md).
 
+### Start and follow a durable execution
+
+```ruby
+project_id = "00000000-0000-4000-8000-000000000001"
+handle = client.durable.start(
+  "charge-order",
+  { order_id: "order-9" },
+  execution_name: "order-9"
+)
+
+execution = client.durable.get(project_id, "charge-order", handle.id)
+puts [execution.status, execution.terminal?, execution.result]
+
+page = client.durable.list(project_id, "charge-order", status: "running")
+puts [page.total, page.has_more]
+
+client.durable.stop(project_id, "charge-order", handle.id)
+```
+
+`start` takes a durable function's name or its id and returns a handle, never a
+result: an execution can run for hours, so its result is read back with `get`.
+It uses the same credential `invoke` does — the active user session, then a
+configured service key, then the anonymous key — and is the only durable
+operation an application credential may perform. An `execution_name` makes the
+start idempotent: starting again under the same name returns the execution that
+already exists rather than beginning a second one.
+
+`get`, `list`, and `stop` are owner-scoped and require a platform token or a
+configured service key, because an execution is addressed by its id alone. An
+auth-user session from sign-in is not accepted. `get` carries the deeply
+frozen `result` once the execution has succeeded, and `error` when it failed;
+`result_expired` separates a result the platform has discarded from a function
+that returned nothing. `terminal?` reports whether the execution has stopped
+changing, and counts `unknown` — the status the platform writes for an outcome
+it could not determine — as finished. `list` returns one page of executions,
+most recent first, each carrying the status last observed rather than a live
+one. `stop` is accepted rather than awaited: what it returns is the execution
+read back after asking, often still `running`, so poll `get` to see it reach
+`stopped`. Repeating a stop is safe.
+
+This gem starts and follows durable executions; it cannot write the durable
+function itself. Checkpointing a handler needs a durable authoring API, and
+there is no Ruby one, so Volcano hosts durable functions on `nodejs22.x`,
+`nodejs24.x`, `python3.13` and `python3.14`. Write the function in JavaScript
+or Python and drive it from Ruby; the operations above are the whole surface a
+caller needs.
+Ruby remains a fully supported runtime for [standard
+functions](https://volcano.dev/platform/functions/overview).
+
 ### Read project logs
 
 ```ruby
@@ -824,6 +873,26 @@ Connection callbacks receive immutable contexts and run outside protocol
 processing. Each registration returns an idempotent callable that stops future
 delivery.
 
+## Dependencies
+
+Installing `volcano-sdk` pulls in eight gems, plus their own transitive
+dependencies:
+
+| Gem                                                          | Why                                                                     |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| [`typhoeus`](https://rubygems.org/gems/typhoeus)             | The HTTP library the generated REST client uses                         |
+| [`logger`](https://rubygems.org/gems/logger)                 | Required by that client, and no longer a default gem                    |
+| [`async`](https://rubygems.org/gems/async)                   | The reactor realtime runs its connection and delivery on                |
+| [`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  |
+| [`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                  |
+
+There is no optional durable dependency, because this gem starts and follows
+durable executions rather than writing them. See
+[Start and follow a durable execution](#start-and-follow-a-durable-execution).
+
 ## Generated boundary
 
 The internal REST transport is generated from `openapi/openapi.yaml`, which

data/lib/volcano/client.rb

@@ -12,7 +12,7 @@ module Volcano
     end
     private_constant :SessionToken
 
-    attr_reader :auth, :functions, :logs, :storage, :locks, :realtime
+    attr_reader :auth, :functions, :durable, :logs, :storage, :locks, :realtime
 
     def initialize(
       anon_key:,
@@ -112,6 +112,7 @@ module Volcano
     def initialize_facades(socket_factory, reconnect_delay)
       @auth = Auth.new(self, @transport, api_url: @api_url)
       @functions = Functions.new(self, @transport, api_url: @api_url)
+      @durable = Durable.new(self, @transport)
       @logs = Logs.new(self, @transport)
       @storage = Storage.new(self, @transport, api_url: @api_url, anon_key: @anon_key)
       @locks = Locks.new(self, @transport)

data/lib/volcano/durable.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+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.
+    EXECUTION_NAME = /\A[A-Za-z0-9._-]{1,255}\z/
+    MAX_PAGE_SIZE = 100
+    include DurableResponses
+
+    def initialize(client, transport)
+      @client = client
+      @transport = transport
+    end
+
+    # Starts an execution and returns its handle. A durable function is never
+    # invoked synchronously: it can outlive any request a caller could hold
+    # open, so its result is read back with #get.
+    #
+    # Starting is the only durable operation an application credential may
+    # perform, and it takes the token an invoke takes. Passing an
+    # +execution_name+ makes the start idempotent: starting again under the
+    # same name returns the execution that already exists rather than
+    # beginning a second one.
+    def start(function_name, payload = {}, execution_name: nil)
+      # A durable function's id is accepted here as well as its name, so the
+      # DNS-safe name pattern an invoke checks would reject half the input.
+      function_id = identifier(function_name, 'function_name')
+      name = execution_name.nil? ? nil : execution_name_argument(execution_name)
+      response = Transport.invoke do
+        @transport.start_durable_execution_from_application(
+          authorization: @client.function_token,
+          function_id: function_id, payload: payload.dup, execution_name: name
+        )
+      end
+      durable_execution(Transport.body(response, 202))
+    end
+
+    # Reads an execution, including its result once it has succeeded.
+    #
+    # Owner-scoped: an execution is addressed by its id alone and an anon key
+    # is held by everyone who loads the page, so this takes the project id and
+    # a platform token or service key. An auth-user session from sign-in is
+    # not enough. Poll it from a backend, not a browser.
+    def get(project_id, function_name, execution_id)
+      project, function_id, execution = execution_path(project_id, function_name, execution_id)
+      response = Transport.invoke do
+        @transport.get_durable_execution(
+          authorization: @client.session_token,
+          project_id: project, function_id: function_id, execution_id: execution
+        )
+      end
+      durable_execution(Transport.body(response, 200))
+    end
+
+    # Lists a durable function's executions, most recent first. Each entry
+    # carries the status the platform last observed rather than a live one;
+    # read a single execution for that. Owner-scoped, like #get.
+    def list(project_id, function_name, status: nil, page: nil, limit: nil)
+      project = identifier(project_id, 'project_id')
+      function_id = identifier(function_name, 'function_name')
+      validate_paging(page, limit)
+      response = Transport.invoke do
+        @transport.list_durable_executions(
+          authorization: @client.session_token, project_id: project, function_id: function_id,
+          options: { status: status, page: page, limit: limit }.compact
+        )
+      end
+      durable_execution_page(Transport.body(response, 200))
+    end
+
+    # Asks a running execution to stop. Accepted rather than awaited: what
+    # comes back is the execution read after asking, and it often still says
+    # +running+, so poll #get to see it reach +stopped+. Completed steps are
+    # not undone, and repeating a stop is safe — an execution that has already
+    # finished reports the state it settled in. Owner-scoped, like #get.
+    def stop(project_id, function_name, execution_id)
+      project, function_id, execution = execution_path(project_id, function_name, execution_id)
+      response = Transport.invoke do
+        @transport.stop_durable_execution(
+          authorization: @client.session_token,
+          project_id: project, function_id: function_id, execution_id: execution
+        )
+      end
+      durable_execution(Transport.body(response, 200))
+    end
+
+    private
+
+    def execution_path(project_id, function_name, execution_id)
+      [
+        identifier(project_id, 'project_id'),
+        identifier(function_name, 'function_name'),
+        identifier(execution_id, 'execution_id')
+      ]
+    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 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)
+        raise ArgumentError,
+              'execution_name must be 1-255 characters of letters, numbers, dots, dashes or underscores'
+      end
+
+      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)
+
+      return if limit.nil? || (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_models.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  DURABLE_EXECUTION_ATTRIBUTES = %i[
+    id function_id name status region created_at result result_expired error completed_at
+  ].freeze
+  private_constant :DURABLE_EXECUTION_ATTRIBUTES
+
+  # `unknown` is terminal, and the platform writes it itself for an execution
+  # whose outcome it could not determine. Code that switches on status has to
+  # treat it as finished, or it reads a finished execution as still running.
+  DURABLE_TERMINAL_STATUSES = %w[succeeded failed timed_out stopped unknown].freeze
+  private_constant :DURABLE_TERMINAL_STATUSES
+
+  # Why a failed or timed-out execution ended.
+  DurableExecutionError = Data.define(:type, :message) do
+    def initialize(type: nil, message: nil)
+      super(type: type&.dup&.freeze, message: message&.dup&.freeze)
+    end
+  end
+
+  # A durable execution, as the platform last observed it.
+  #
+  # `result` is absent while the execution is still running, and absent again
+  # 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.
+  DurableExecution = Data.define(*DURABLE_EXECUTION_ATTRIBUTES) do
+    def initialize(**attributes)
+      unknown = attributes.keys - DURABLE_EXECUTION_ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      missing = DURABLE_EXECUTION_ATTRIBUTES.first(6) - attributes.keys
+      raise ArgumentError, "missing keywords: #{missing.join(', ')}" unless missing.empty?
+
+      values = DURABLE_EXECUTION_ATTRIBUTES.to_h do |name|
+        [name, immutable_value(attributes[name])]
+      end
+      super(**values)
+    end
+
+    # Reports whether the execution has stopped changing.
+    def terminal?
+      DURABLE_TERMINAL_STATUSES.include?(status)
+    end
+
+    private
+
+    # `result` is the function's own JSON, so it is frozen all the way down.
+    def immutable_value(value)
+      case value
+      when Hash then value.to_h { |key, item| [immutable_value(key), immutable_value(item)] }.freeze
+      when Array then value.map { |item| immutable_value(item) }.freeze
+      when Time, String then value.dup.freeze
+      else value
+      end
+    end
+  end
+
+  # One page of a durable function's executions, most recent first.
+  DurableExecutionPage = Data.define(:executions, :page, :limit, :total, :has_more) do
+    def initialize(executions:, page:, limit:, total:, has_more:)
+      super(
+        executions: executions.to_a.dup.freeze,
+        page: page, limit: limit, total: total, has_more: has_more
+      )
+    end
+  end
+
+  # Builds the public durable types from transport payloads.
+  module DurableResponses
+    INCOMPLETE_EXECUTION = 'Expected a complete durable execution'
+    INCOMPLETE_PAGE = 'Expected a complete durable execution page'
+    EXECUTION_FIELDS = %w[id function_id name status region].freeze
+    private_constant :INCOMPLETE_EXECUTION, :INCOMPLETE_PAGE, :EXECUTION_FIELDS
+
+    private
+
+    def durable_execution(payload)
+      values = execution_payload(payload)
+      DurableExecution.new(
+        id: values.fetch('id'), function_id: values.fetch('function_id'),
+        name: values.fetch('name'), status: values.fetch('status'),
+        region: values.fetch('region'), created_at: parse_time(values.fetch('created_at')),
+        result: values['result'], result_expired: values['result_expired'],
+        error: execution_error(values['error']), completed_at: parse_time(values['completed_at'])
+      )
+    end
+
+    def execution_payload(payload)
+      raise TypeError, INCOMPLETE_EXECUTION unless payload.is_a?(Hash)
+
+      complete = EXECUTION_FIELDS.all? { |field| present_string?(payload[field]) }
+      raise TypeError, INCOMPLETE_EXECUTION unless complete && payload['created_at']
+
+      payload
+    end
+
+    def execution_error(payload)
+      return if payload.nil?
+      raise TypeError, INCOMPLETE_EXECUTION unless payload.is_a?(Hash)
+
+      DurableExecutionError.new(type: payload['type'], message: payload['message'])
+    end
+
+    def durable_execution_page(payload)
+      data, has_more = page_payload(payload)
+      DurableExecutionPage.new(
+        executions: data.map { |entry| durable_execution(entry) }, has_more: has_more,
+        page: count(payload['page']), limit: count(payload['limit']), total: count(payload['total'])
+      )
+    end
+
+    # An empty page carries no executions at all rather than an empty array.
+    def page_payload(payload)
+      raise TypeError, INCOMPLETE_PAGE unless payload.is_a?(Hash)
+
+      data = payload['data'] || []
+      has_more = payload.fetch('has_more', false)
+      raise TypeError, INCOMPLETE_PAGE unless data.is_a?(Array) && [true, false].include?(has_more)
+
+      [data, has_more]
+    end
+
+    def count(value)
+      return 0 if value.nil?
+      raise TypeError, INCOMPLETE_PAGE unless value.is_a?(Integer)
+
+      value
+    end
+
+    def present_string?(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+
+    def parse_time(value)
+      value.is_a?(String) ? Time.iso8601(value) : value
+    end
+  end
+  private_constant :DurableResponses
+end

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

@@ -428,7 +428,7 @@ module Volcano::Generated
     end
 
     # List platform-supported regions for database provisioning
-    # Returns the regions enabled for database provisioning in this platform environment. This is a public endpoint that doesn't require authentication. 
+    # Returns the regions enabled for database provisioning in this platform environment. These are the same regions offered for function deployment, and the only values the `region` field of a database accepts. This is a public endpoint that doesn't require authentication. 
     # @param [Hash] opts the optional parameters
     # @return [Array<ListDatabaseRegions200ResponseInner>]
     def list_database_regions(opts = {})
@@ -437,7 +437,7 @@ module Volcano::Generated
     end
 
     # List platform-supported regions for database provisioning
-    # Returns the regions enabled for database provisioning in this platform environment. This is a public endpoint that doesn&#39;t require authentication. 
+    # Returns the regions enabled for database provisioning in this platform environment. These are the same regions offered for function deployment, and the only values the &#x60;region&#x60; field of a database accepts. This is a public endpoint that doesn&#39;t require authentication. 
     # @param [Hash] opts the optional parameters
     # @return [Array<(Array<ListDatabaseRegions200ResponseInner>, Integer, Hash)>] Array<ListDatabaseRegions200ResponseInner> data, response status code and response headers
     def list_database_regions_with_http_info(opts = {})