runtype 0.2.2 → 0.5.0

data/lib/runtype/agent_release_aliases.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+require "timeout"
+
+module Runtype
+  # Release aliases and deployment receipts on {Runtype::Client}. An agent runs
+  # an immutable version; a named mutable alias (`live`, `pr-482`) selects which
+  # one, and every activation appends a deployment receipt. Protocol:
+  # `docs/adr/0025-agent-release-aliases.md`.
+  module AgentReleaseAliases
+    # The fields a `promotion:` hash may carry, mirroring the API's strict
+    # `AgentDeploymentPromotion` schema (apps/api/src/routes/agents/alias-routes.ts)
+    # and the generated {Runtype::Types::AgentDeploymentPromotion} model.
+    PROMOTION_FIELDS = %i[source_agent_id source_version_id source_content_hash source_commit].freeze
+
+    # The failures one {#archive_agent_alias_everywhere} row may absorb: the
+    # curated API tree, plus the transport exceptions Net::HTTP raises below
+    # {Runtype.wrap_errors} (the same set {Runtype::Streaming::Connection}
+    # translates). Everything else is an SDK defect rather than a per-agent
+    # outcome and aborts the sweep loudly instead of becoming a failure row.
+    SWEEP_ISOLATED_ERRORS = [
+      Runtype::Error, Timeout::Error, OpenSSL::SSL::SSLError, SocketError, SystemCallError, IOError
+    ].freeze
+
+    # The named pointers of one agent: `live` first, then the preview aliases by
+    # name. Archived aliases are omitted unless asked for. Omitting `limit:`
+    # returns every pointer; supplying it pages through the same order.
+    #
+    # @param agent_id [String]
+    # @param include_archived [Boolean]
+    # @param limit [Integer, String, nil]
+    # @param cursor [String, nil] from a previous page's `nextCursor`.
+    # @param request_options [Hash] see {Runtype::Client#dispatch}.
+    # @return [Runtype::AgentAliases::Types::GetV1AgentsIDAliasesResponse]
+    def list_agent_aliases(agent_id, include_archived: false, limit: nil, cursor: nil, request_options: {})
+      params = { id: agent_id, limit: limit, cursor: cursor }.compact
+      params[:include_archived] = "true" if include_archived
+      Runtype.wrap_errors do
+        release_alias_client.list_release_aliases_for_an_agent(request_options: request_options, **params)
+      end
+    end
+
+    # One pointer. A missing or archived alias answers a structured 404 naming
+    # the alias; it never falls back to `live`.
+    #
+    # @param agent_id [String]
+    # @param alias_name [String] e.g. `"live"` or `"pr-482"`.
+    # @param include_archived [Boolean]
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::GetV1AgentsIDAliasesAliasResponse]
+    # @raise [Runtype::NotFoundError] when no such alias is in scope.
+    def get_agent_alias(agent_id, alias_name, include_archived: false, request_options: {})
+      params = { id: agent_id, alias_: alias_name }
+      params[:include_archived] = "true" if include_archived
+      Runtype.wrap_errors do
+        release_alias_client.get_one_release_alias(request_options: request_options, **params)
+      end
+    end
+
+    # Aims one alias at one immutable version of the same agent, appending a
+    # deployment receipt in the same transaction. `version_id` is sent exactly as
+    # given: an alias is never resolved to a version client-side.
+    #
+    # @param agent_id [String]
+    # @param alias_name [String]
+    # @param version_id [String] the exact version to activate.
+    # @param revision [String, nil] the alias revision this activation expects,
+    #   sent as `If-Match`; required when moving an existing `live` pointer.
+    # @param idempotency_key [String, nil] replays the same activation safely.
+    # @param reason [String, nil] recorded on the receipt.
+    # @param promotion [Hash, Runtype::Types::AgentDeploymentPromotion, nil] the
+    #   source-organization ids and hashes a cross-organization promotion came
+    #   from, e.g. `{ source_version_id: "agv_9", source_commit: sha }`, linked
+    #   on the receipt. Provenance only: it authorizes nothing, and the
+    #   activating credentials alone decide what the activation may do.
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::PutV1AgentsIDAliasesAliasResponse]
+    # @raise [ArgumentError] when `promotion:` carries an unrecognized key.
+    def activate_agent_alias(agent_id, alias_name, version_id:, revision: nil, idempotency_key: nil, reason: nil,
+                             promotion: nil, request_options: {})
+      params = {
+        id: agent_id, alias_: alias_name, version_id: version_id,
+        if_match: revision, idempotency_key: idempotency_key, reason: reason,
+        promotion: promotion_provenance(promotion)
+      }.compact
+      Runtype.wrap_errors do
+        release_alias_client.activate_a_version_at_a_release_alias(request_options: request_options, **params)
+      end
+    end
+
+    # Archives a preview alias: it stops resolving for new executions, keeps its
+    # deployment history, and does not interrupt admitted runs. The row is never
+    # deleted, so a later activation revives the same pointer. `live` cannot be
+    # archived.
+    #
+    # @param agent_id [String]
+    # @param alias_name [String]
+    # @param revision [String, nil] sent as `If-Match`.
+    # @param idempotency_key [String, nil]
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::DeleteV1AgentsIDAliasesAliasResponse]
+    def archive_agent_alias(agent_id, alias_name, revision: nil, idempotency_key: nil, request_options: {})
+      params = {
+        id: agent_id, alias_: alias_name, if_match: revision, idempotency_key: idempotency_key
+      }.compact
+      Runtype.wrap_errors do
+        release_alias_client.archive_a_release_alias(request_options: request_options, **params)
+      end
+    end
+
+    # Re-aims an alias at the version recorded as `previousVersionId` on its most
+    # recent pointer-moving receipt, walking `steps:` receipts back, and writes a
+    # `rollback` receipt. Restores configuration only: external data and side
+    # effects are not rolled back.
+    #
+    # @param agent_id [String]
+    # @param alias_name [String]
+    # @param steps [Integer, nil] how many receipts to walk back; default 1.
+    # @param revision [String, nil] sent as `If-Match`.
+    # @param idempotency_key [String, nil]
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::PostV1AgentsIDAliasesAliasRollbackResponse]
+    def rollback_agent_alias(agent_id, alias_name, steps: nil, revision: nil, idempotency_key: nil,
+                             request_options: {})
+      params = {
+        id: agent_id, alias_: alias_name, steps: steps, if_match: revision, idempotency_key: idempotency_key
+      }.compact
+      Runtype.wrap_errors do
+        release_alias_client.roll_a_release_alias_back_to_its_previous_version(
+          request_options: request_options, **params
+        )
+      end
+    end
+
+    # The append-only deployment history of one agent, newest first,
+    # cursor-paginated. Each receipt records the pointer, the previous and new
+    # versions, the alias revision, the actor, provenance and the dependency
+    # fingerprints checked at activation.
+    #
+    # @param agent_id [String]
+    # @param alias_name [String, nil] narrows the history to one pointer.
+    # @param limit [Integer, String, nil]
+    # @param cursor [String, nil]
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::GetV1AgentsIDDeploymentsResponse]
+    def list_agent_deployments(agent_id, alias_name: nil, limit: nil, cursor: nil, request_options: {})
+      params = { id: agent_id, alias_: alias_name, limit: limit, cursor: cursor }.compact
+      Runtype.wrap_errors do
+        release_alias_client.list_deployment_receipts_for_an_agent(request_options: request_options, **params)
+      end
+    end
+
+    # Every agent in the caller's organization carrying a pointer with this
+    # name, each with the revision to quote back as `If-Match`. This is the read
+    # a "pull request closed" cleanup makes before archiving each pointer; the
+    # per-agent list would need every agent id first. Unpaginated, and `live` is
+    # readable here like any other name.
+    #
+    # @param alias_name [String] e.g. `"pr-482"`.
+    # @param include_archived [Boolean]
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::GetV1AgentAliasesResponse]
+    def list_agent_aliases_by_name(alias_name, include_archived: false, request_options: {})
+      params = { alias_: alias_name }
+      params[:include_archived] = "true" if include_archived
+      Runtype.wrap_errors do
+        release_alias_client.list_release_aliases_with_one_name_across_the_organization(
+          request_options: request_options, **params
+        )
+      end
+    end
+
+    # Archives this pointer on every agent in the organization that carries it,
+    # each under the revision just read, so a concurrent deploy answers 412
+    # instead of racing. An API refusal or transport failure on one agent is
+    # reported in `"failed"` and the sweep continues; any other exception is an
+    # SDK defect and propagates, so a broken response contract never reads as a
+    # completed sweep. Only active pointers are listed, so a second run archives
+    # nothing.
+    #
+    # @param alias_name [String]
+    # @param dry_run [Boolean] report what would be archived and archive nothing.
+    # @param request_options [Hash]
+    # @return [Hash] `{"alias", "archived" => [{"agentId", "agentName",
+    #   "revision", "receiptId"}], "failed" => [{"agentId", "agentName",
+    #   "error", "code"?}]}`, or for a dry run `{"alias", "dryRun" => true,
+    #   "wouldArchive" => [<row>]}` carrying the listed rows unchanged.
+    def archive_agent_alias_everywhere(alias_name, dry_run: false, request_options: {})
+      rows = list_agent_aliases_by_name(alias_name, request_options: request_options).data
+      return { "alias" => alias_name, "dryRun" => true, "wouldArchive" => rows } if dry_run
+
+      rows.each_with_object({ "alias" => alias_name, "archived" => [], "failed" => [] }) do |row, sweep|
+        sweep["archived"] << archive_one_everywhere(row, alias_name, request_options)
+      # Wider than Runtype::Error: a DNS, TLS or connection-reset failure is
+      # raised by Net::HTTP and never reaches Runtype.wrap_errors, so rescuing
+      # the curated tree alone would abort the sweep on one bad row and leave the
+      # remaining pointers active — the opposite of what this method promises.
+      rescue *SWEEP_ISOLATED_ERRORS => e
+        sweep["failed"] << {
+          "agentId" => row.agent_id, "agentName" => row.agent_name,
+          "error" => e.message, "code" => alias_failure_code(e)
+        }.compact
+      end
+    end
+
+    private
+
+    # @return [Runtype::AgentAliases::Client] the generated sub-client these
+    #   wrappers delegate to, with the curated error surface layered on top.
+    def release_alias_client
+      api.agent_aliases
+    end
+
+    # One row of an {#archive_agent_alias_everywhere} sweep. The revision and
+    # receipt reported are the archive response's, not the listed row's.
+    #
+    # @param row [Runtype::AgentAliases::Types::GetV1AgentAliasesResponseDataItem]
+    # @param alias_name [String]
+    # @param request_options [Hash]
+    # @return [Hash]
+    def archive_one_everywhere(row, alias_name, request_options)
+      archived = archive_agent_alias(
+        row.agent_id, alias_name, revision: row.revision.to_s, request_options: request_options
+      )
+      {
+        "agentId" => row.agent_id, "agentName" => row.agent_name,
+        "revision" => archived.revision, "receiptId" => archived.receipt_id
+      }
+    end
+
+    # The alias plane's refusal code for a failed sweep row, matching the
+    # TypeScript helper's `code` field. 428 carries no code of its own, so the
+    # one the typed error uses is supplied here.
+    #
+    # @param error [Runtype::Error]
+    # @return [String, nil]
+    def alias_failure_code(error)
+      body = error.respond_to?(:body) ? error.body : nil
+      code = body["code"] if body.is_a?(Hash)
+      return code.to_s if code
+
+      "alias_revision_required" if error.respond_to?(:status_code) && error.status_code == 428
+    end
+
+    # Normalizes `promotion:` into the wire shape. A generated
+    # {Runtype::Types::AgentDeploymentPromotion} passes through; a Hash may spell
+    # its keys either way, and an unknown key raises here rather than reaching
+    # the server's strict 400 — or, worse, being absorbed as an extra field on
+    # the generated request model. An all-nil hash is treated as omitted, the
+    # same reading the API gives an empty promotion object.
+    #
+    # @param promotion [Hash, Runtype::Types::AgentDeploymentPromotion, nil]
+    # @return [Hash, Runtype::Types::AgentDeploymentPromotion, nil]
+    # @raise [ArgumentError] on a non-Hash or an unrecognized key.
+    def promotion_provenance(promotion)
+      return nil if promotion.nil?
+      return promotion if promotion.is_a?(Runtype::Types::AgentDeploymentPromotion)
+
+      unless promotion.is_a?(Hash)
+        raise ArgumentError,
+              "promotion: needs a Hash of source ids, e.g. promotion: { source_version_id: \"agv_9\" }."
+      end
+
+      provenance = promotion.each_with_object({}) do |(key, value), acc|
+        field = promotion_field(key)
+        raise ArgumentError, "promotion: accepts #{PROMOTION_FIELDS.join(", ")}, not #{key.inspect}." unless field
+
+        acc[field] = value.to_s unless value.nil?
+      end
+      provenance.empty? ? nil : provenance
+    end
+
+    # @param key [String, Symbol] either spelling of a promotion field.
+    # @return [Symbol, nil] the snake_case field name, or nil when unrecognized.
+    def promotion_field(key)
+      field = key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      PROMOTION_FIELDS.include?(field) ? field : nil
+    end
+  end
+end

data/lib/runtype/client.rb

@@ -26,6 +26,7 @@ module Runtype
   # clients with different keys or base URLs can coexist in one process.
   class Client
     include Runtype::AgentEnsure
+    include Runtype::AgentReleaseAliases
     include Runtype::LocalToolRunner
 
     # Per-operation socket timeout, in seconds. Generous by default: an
@@ -52,7 +53,10 @@ module Runtype
 
     # @param api_key [String, nil] defaults to `RUNTYPE_API_KEY`.
     # @param base_url [String] defaults to `RUNTYPE_BASE_URL`, then production.
-    # @param timeout [Numeric, nil] per-operation socket timeout in seconds.
+    # @param timeout [Numeric, nil] per-operation socket timeout in seconds,
+    #   defaulting to {DEFAULT_TIMEOUT}. Governs the dispatch and streaming
+    #   paths and every generated resource call alike; a single call overrides
+    #   it with `request_options: { timeout_in_seconds: n }`.
     # @param max_retries [Integer] retries for generated resource calls. The
     #   dispatch paths never retry: replaying an execution would run it twice.
     # @raise [Runtype::AuthenticationError] when no API key is available.
@@ -78,6 +82,8 @@ module Runtype
         authorization: bearer_token,
         max_retries: max_retries
       )
+      # WORKAROUND(fern ruby generator): BaseClient takes no timeout, so seed the transport it just built.
+      Runtype::RawClientTimeout.apply(generated_raw_client, timeout: @timeout)
     end
 
     # Executes a flow or agent and waits for the complete JSON response.
@@ -192,6 +198,21 @@ module Runtype
 
     private
 
+    # The transport {#api} shares with every resource sub-client it builds.
+    # Read once at construction, before any sub-client has memoized it.
+    #
+    # @return [Runtype::Internal::Http::RawClient]
+    # @raise [Runtype::Error] when the generated core no longer holds one, which
+    #   means the timeout can no longer be applied to generated calls.
+    def generated_raw_client
+      raw = @api.instance_variable_get(:@raw_client)
+      return raw if raw.is_a?(Runtype::Internal::Http::RawClient)
+
+      raise Runtype::Error,
+            "Runtype::BaseClient no longer exposes @raw_client, so Runtype::Client cannot apply its timeout " \
+            "to generated calls. Rewire Runtype::RawClientTimeout against the generated core's new shape."
+    end
+
     # @return [String]
     def bearer_token
       "Bearer #{@api_key}"

data/lib/runtype/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Runtype
   # Base class for every error the overlay raises. Rescue this to catch all of
   # them regardless of which generated resource produced the failure.
@@ -28,12 +30,20 @@ module Runtype
     # Translates a Fern-generated error into the curated equivalent. Errors that
     # are not generated API errors are returned unchanged.
     #
+    # A socket timeout is translated too: the generated methods rescue
+    # `Net::HTTPRequestTimeout`, a 408 response class no socket ever raises, so
+    # `Net::OpenTimeout`, `Net::ReadTimeout` and `Net::WriteTimeout` reach here
+    # untranslated. They all descend from `Timeout::Error`, so one clause covers
+    # connect, read and write, matching {Runtype::Streaming::Connection}.
+    #
     # @param error [Exception]
     # @return [Exception]
     def self.from_generated(error)
       case error
       when Runtype::Errors::TimeoutError
         APITimeoutError.new("Request timed out")
+      when ::Timeout::Error
+        APITimeoutError.new("Request timed out: #{error.message}")
       when Runtype::Errors::ResponseError
         from_response(status: error.code, body: error.message)
       when Runtype::Errors::ApiError
@@ -235,7 +245,9 @@ module Runtype
   class APIConnectionError < Error; end
 
   # Runs a block, re-raising Fern-generated errors as their curated equivalents
-  # so callers keep one stable rescue surface across regenerations.
+  # so callers keep one stable rescue surface across regenerations. A socket
+  # timeout raised inside a generated call is curated here too, as
+  # {Runtype::APITimeoutError}.
   #
   # @example
   #   Runtype.wrap_errors { client.flows.list_flows }
@@ -243,7 +255,7 @@ module Runtype
   # @return [Object] whatever the block returns.
   def self.wrap_errors
     yield
-  rescue Runtype::Errors::ApiError => e
+  rescue Runtype::Errors::ApiError, ::Timeout::Error => e
     raise Runtype::Error.from_generated(e)
   end
 end

data/lib/runtype/raw_client_timeout.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Runtype
+  # Timeout handling for the Fern-generated low-level transport.
+  #
+  # `Runtype::BaseClient` accepts no timeout and builds its
+  # `Runtype::Internal::Http::RawClient` with the generator's 60 second default,
+  # so every generated resource call ignored the timeout {Runtype::Client} was
+  # given. {Runtype::Client} seeds that transport through {apply}, which also
+  # gives it the per-call `request_options[:timeout_in_seconds]` override the
+  # generated methods document.
+  module RawClientTimeout
+    # Sends one request under the caller's `timeout_in_seconds` when it asked
+    # for one, and under the client-wide timeout otherwise. The override runs
+    # on a copy of the transport, so a client shared across threads is never
+    # mutated for the duration of one call.
+    #
+    # @param request [Runtype::Internal::Http::BaseRequest]
+    # @return [Net::HTTPResponse]
+    def send(request)
+      seconds = RawClientTimeout.timeout_in_seconds(request)
+      return super if seconds.nil? || seconds == @timeout
+
+      scoped = dup
+      scoped.instance_variable_set(:@timeout, seconds)
+      # INVARIANT: the copy's own timeout equals the override, so its send takes the branch above and cannot recur.
+      scoped.send(request)
+    end
+
+    # Reads the per-request timeout off a request's options under either key
+    # spelling, matching {Runtype::Client}'s streaming path.
+    #
+    # @param request [Runtype::Internal::Http::BaseRequest]
+    # @return [Float, nil] nil when no override was asked for, or when the
+    #   value is not a number.
+    def self.timeout_in_seconds(request)
+      options = request.respond_to?(:request_options) ? request.request_options : nil
+      return nil unless options.respond_to?(:[])
+
+      value = options[:timeout_in_seconds] || options["timeout_in_seconds"]
+      value.nil? ? nil : Float(value, exception: false)
+    end
+
+    # Seeds a generated transport with the client-wide timeout and gives it
+    # per-request override handling.
+    #
+    # @param raw_client [Runtype::Internal::Http::RawClient]
+    # @param timeout [Numeric] the client-wide timeout, in seconds.
+    # @return [Runtype::Internal::Http::RawClient] the same object.
+    def self.apply(raw_client, timeout:)
+      raw_client.instance_variable_set(:@timeout, Float(timeout))
+      raw_client.extend(self)
+      raw_client
+    end
+  end
+end

data/lib/runtype/sdk_version.rb

@@ -8,7 +8,8 @@ module Runtype
   # generator). The generated barrel does not require that file, so nothing
   # collides today, but re-declaring it here would make the overlay's version
   # depend on generator require order.
-  SDK_VERSION = "0.2.2"
+  # Mirrored from ../../package.json by scripts/sync-sdk-versions.mjs; never hand-edit.
+  SDK_VERSION = "0.5.0"
 
   # Outbound User-Agent identifying the SDK kind, version, and language, e.g.
   # "runtype-sdk/0.1.0 (ruby)". The `runtype-sdk/` prefix is what the API's

data/lib/runtype.rb

@@ -25,6 +25,7 @@ require_relative "../generated/lib/runtype"
 
 require_relative "runtype/sdk_version"
 require_relative "runtype/errors"
+require_relative "runtype/raw_client_timeout"
 require_relative "runtype/streaming/event"
 require_relative "runtype/streaming/line_decoder"
 require_relative "runtype/streaming/event_parser"
@@ -33,6 +34,7 @@ require_relative "runtype/streaming/event_stream"
 require_relative "runtype/canonical_json"
 require_relative "runtype/agent_definition"
 require_relative "runtype/agent_ensure"
+require_relative "runtype/agent_release_aliases"
 require_relative "runtype/local_tools"
 require_relative "runtype/detached_follow"
 require_relative "runtype/local_tool_runner"