temper-rb 0.5.1

data/lib/temper/contexts.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Temper
+  class Contexts
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /api/contexts -> 201 ContextRow.
+    #
+    # ContextCreateRequest's fields are `name` and `owner`; only `name` is
+    # required, and there is no `slug` on the wire -- the server derives it.
+    def create(name:, owner: nil)
+      attrs = { name: name }
+      attrs[:owner] = owner_ref(owner) unless owner.nil?
+      body = Generated::ContextCreateRequest.new(attrs)
+      @client.call { |api| Generated::ContextsApi.new(api).create_context(body) }
+    end
+
+    def list(**filters)
+      @client.call(idempotent: true) { |api| Generated::ContextsApi.new(api).list_contexts(filters) }
+    end
+
+    def show(ref)
+      id = Temper.parse_ref(ref)
+      @client.call(idempotent: true) { |api| Generated::ContextsApi.new(api).get_context(id) }
+    end
+
+    private
+
+    # ContextOwnerRef is an externally-tagged serde enum mixing a unit variant
+    # with newtype variants, so it has no discriminator and the generated oneOf
+    # wrapper is best-effort by its own admission ("we do not attempt to check
+    # whether exactly one item matches"). We build the wire shape directly and
+    # let the generated model carry it: to_hash passes non-model values verbatim.
+    #
+    # Unencodable input is an error, never a guess.
+    def owner_ref(owner)
+      case owner
+      when :me, 'me' then 'Me'
+      when Hash then hash_owner_ref(owner)
+      else
+        raise ArgumentError, "owner must be :me, {team:}, or {profile:}, got #{owner.inspect}"
+      end
+    end
+
+    def hash_owner_ref(owner)
+      return { 'Team' => owner.fetch(:team) } if owner.key?(:team)
+      return { 'Profile' => owner.fetch(:profile) } if owner.key?(:profile)
+
+      raise ArgumentError, "owner Hash must carry :team or :profile, got #{owner.keys.inspect}"
+    end
+  end
+end

data/lib/temper/credentials.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'uri'
+
+module Temper
+  # Two strategies behind one interface. Precedence is not discovered from the
+  # environment -- it is the caller's explicit choice. That avoids, structurally,
+  # the drift the steward's temper-auth.ts header documents: its schedules went
+  # Connect-first while its MCP connection went M2M-first, so on the Auth0-fronted
+  # prod instance the schedules' REST calls silently failed while MCP worked.
+  module Credentials
+    # A token the caller already holds -- a Puma request serving a signed-in user.
+    # No I/O, no refresh.
+    class BearerToken
+      def initialize(token)
+        raise ArgumentError, 'token must be a non-empty String' unless token.is_a?(String) && !token.empty?
+
+        @token = token
+      end
+
+      attr_reader :token
+
+      def refresh!
+        raise Unauthorized.new('BearerToken cannot refresh; mint a new token upstream', status: 401)
+      end
+    end
+
+    # A client_credentials machine principal -- a Sidekiq worker.
+    #
+    # Works against BOTH issuers a temper instance can be fronted by:
+    #
+    #   * Auth0 (`temper admin machine provision`), where `token_url` is your Auth0
+    #     tenant's /oauth/token and `audience` must equal the API's AUTH_AUDIENCE.
+    #   * temper's own AS (`temper admin machine issue`, a `tmpr_*` client id), where
+    #     `token_url` is your own instance's /oauth/token and `audience` is omitted --
+    #     that AS mints with its server-side AS_AUDIENCE and ignores a request-supplied
+    #     one entirely.
+    #
+    # Ported from packages/agent-workflows/steward/agent/lib/temper-auth.ts, the
+    # machine-principal caller already running in production: the same TEMPER_M2M_*
+    # inputs, `requireEnv` semantics (throw, never default), and a cache keyed on an
+    # ABSOLUTE expires_at with a 60s skew.
+    #
+    # Two deliberate divergences from that reference:
+    #
+    #   * The cache is mutex-guarded. The steward's is a bare module global, sound
+    #     only because a serverless function is single-threaded. Under Puma every
+    #     in-flight thread races to mint at expiry.
+    #   * #refresh! exists. Refresh-ahead-of-expiry alone is insufficient: the
+    #     steward resolves a token once per tick, so a tick outliving its cached
+    #     token takes a 401 nothing recovers. A Sidekiq job holding a token across
+    #     a long unit of work has precisely that bug. Re-mint ON 401.
+    class ClientCredentials
+      SKEW_SECONDS = 60
+      TOKEN_REQUEST_CONTENT_TYPE = 'application/x-www-form-urlencoded'
+
+      # `audience` is optional because it is Auth0's, not the protocol's. Omit it for a
+      # temper-issued credential.
+      def initialize(token_url:, client_id:, client_secret:, audience: nil, clock: -> { Time.now },
+                     allow_insecure_http: false)
+        # The client_secret goes on the wire to this URL on every mint, so the
+        # scheme is checked at construction -- refused here, not flagged per mint.
+        Validate.require_endpoint(token_url, name: 'token_url',
+                                             allow_insecure_http: allow_insecure_http)
+        @token_url = require_value(token_url, 'token_url')
+        @client_id = require_value(client_id, 'client_id')
+        @client_secret = require_value(client_secret, 'client_secret')
+        @audience = audience.nil? ? nil : require_value(audience, 'audience')
+        @clock = clock
+        @mutex = Mutex.new
+        @token = nil
+        @expires_at = nil
+      end
+
+      def token
+        @mutex.synchronize do
+          mint! if expired?
+          @token
+        end
+      end
+
+      def refresh!
+        @mutex.synchronize { mint! }
+      end
+
+      private
+
+      def require_value(value, name)
+        raise ArgumentError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+
+        value
+      end
+
+      def expired?
+        @token.nil? || @clock.call.to_f >= (@expires_at - SKEW_SECONDS)
+      end
+
+      # Caller holds @mutex.
+      def mint!
+        body = JSON.parse(post_token_request.body)
+        @token = body.fetch('access_token')
+        # Absolute, not relative: a duration cannot survive being cached.
+        @expires_at = @clock.call.to_f + body.fetch('expires_in').to_i
+        @token
+      end
+
+      def post_token_request
+        response = Faraday.post(@token_url) do |req|
+          req.headers['Content-Type'] = TOKEN_REQUEST_CONTENT_TYPE
+          req.body = token_request_body
+        end
+        return response if response.success?
+
+        raise Unauthorized.new("token mint failed (#{response.status})",
+                               status: response.status, details: response.body)
+      end
+
+      # RFC 6749 §4 mandates form encoding at the token endpoint. Auth0 also accepts
+      # JSON, which is why this sent JSON while Auth0 was the only issuer it faced --
+      # and why every test stayed green. Temper's own AS reads the body with
+      # `req.formData()`, so a JSON mint never reaches its client_credentials branch.
+      # Form-encoding is what both issuers accept.
+      def token_request_body
+        params = {
+          grant_type: 'client_credentials',
+          client_id: @client_id,
+          client_secret: @client_secret
+        }
+        # Auth0 requires it; temper's AS ignores a request-supplied audience and mints
+        # with its own AS_AUDIENCE. Sending an empty one would be a lie, so omit it.
+        params[:audience] = @audience unless @audience.nil?
+        URI.encode_www_form(params)
+      end
+    end
+  end
+end

data/lib/temper/errors.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Temper
+  class Error < StandardError
+    attr_reader :status, :code, :details
+
+    def initialize(message = nil, status: nil, code: nil, details: nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+    end
+  end
+
+  # Let these escape: Sidekiq retries a job whose exception escapes.
+  class TransientError < Error; end
+
+  class RateLimited < TransientError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  class ServerError < TransientError; end
+  class ConnectionError < TransientError; end
+
+  # Rescue these: retrying will not help. Dead-letter them.
+  class PermanentError < Error; end
+
+  class Unauthorized < PermanentError; end
+  class Forbidden < PermanentError; end
+
+  # The one error whose `#details` is a typed payload rather than a free-form blob: the server
+  # says *why* it refused, so a worker can tell "never granted" from "granted and then revoked"
+  # without matching on the message string.
+  class SystemAccessRequired < Forbidden
+    # The refusal as a generated model — `Denied`, `Revoked`, `IllegalTransition`, and so on.
+    #
+    # `nil` means this build cannot name the refusal: either the server sent none (it predates the
+    # typed 403) or it sent a kind added after this gem was generated. Reach for #refusal_kind in
+    # that case — a name we cannot resolve is still worth logging.
+    def refusal
+      raw = refusal_hash
+      # The generated oneOf dispatcher matches on SYMBOL keys, because the ApiClient deserializes
+      # with symbolize_names. #details comes off the error envelope with string keys, and feeding
+      # those in resolves to nil SILENTLY — so the symbolize belongs here, once, not in every
+      # caller. The refusal payload is flat, so shallow is sufficient.
+      raw && Temper::Generated::Refusal.build(raw.transform_keys(&:to_sym))
+    end
+
+    # The refusal's discriminator as the server sent it, resolvable or not.
+    def refusal_kind
+      refusal_hash&.fetch('kind', nil)
+    end
+
+    private
+
+    def refusal_hash
+      return nil unless details.is_a?(Hash)
+
+      raw = details['refusal']
+      raw.is_a?(Hash) ? raw : nil
+    end
+  end
+
+  class NotFound < PermanentError; end
+  class Conflict < PermanentError; end
+  class BadRequest < PermanentError; end
+
+  # Translates the generated core's one flat ApiError into the tree above.
+  #
+  # The split is load-bearing rather than decorative: a 409 classified transient
+  # spins a Sidekiq job forever, and a 503 classified permanent is silently
+  # dropped.
+  module ErrorMapper
+    SYSTEM_ACCESS_REQUIRED = 'SYSTEM_ACCESS_REQUIRED'
+
+    # 422 is declared on no operation but is what a serde rejection surfaces as.
+    # 403 and 429 are not here: each needs more than the status to classify.
+    STATUS_CLASSES = {
+      400 => BadRequest,
+      401 => Unauthorized,
+      404 => NotFound,
+      409 => Conflict,
+      422 => BadRequest
+    }.freeze
+
+    module_function
+
+    def call(api_error)
+      status = api_error.code
+      code, message, details = parse_envelope(api_error.response_body)
+      # ApiError#message decorates itself with status/headers/body when it has
+      # them. A transport failure has none, so this fallback stays clean.
+      message ||= api_error.message
+      kwargs = { status: status, code: code, details: details }
+
+      # A nil status means the generated ApiClient rescued a Faraday transport
+      # failure (timeout / connection refused) and re-raised it code-less.
+      return ConnectionError.new(message, **kwargs) if status.nil?
+
+      build(status, message, code, kwargs, api_error)
+    end
+
+    def build(status, message, code, kwargs, api_error)
+      # 403 discriminates on error.code; 429 carries Retry-After. Everything else
+      # classifies off the status alone.
+      return forbidden(code, message, kwargs) if status == 403
+      return RateLimited.new(message, retry_after: retry_after_of(api_error), **kwargs) if status == 429
+
+      klass = STATUS_CLASSES[status] || (server_error?(status) ? ServerError : Error)
+      klass.new(message, **kwargs)
+    end
+
+    def server_error?(status)
+      (500..599).cover?(status)
+    end
+
+    def forbidden(code, message, kwargs)
+      return SystemAccessRequired.new(message, **kwargs) if code == SYSTEM_ACCESS_REQUIRED
+
+      Forbidden.new(message, **kwargs)
+    end
+
+    # The server speaks exactly one envelope: {"error":{code,message,details}}.
+    # Anything else -- an HTML 502 from a proxy, an undeclared 500 -- degrades to
+    # a raw body on #details rather than raising inside the error path.
+    #
+    # 422/429/500/503 are declared on NO operation, so those bodies are parsed
+    # opportunistically and classified off the raw HTTP status.
+    def parse_envelope(body)
+      return [nil, nil, nil] if body.nil? || body.to_s.empty?
+
+      parsed = JSON.parse(body.to_s)
+      error = parsed.is_a?(Hash) ? parsed['error'] : nil
+      return [nil, nil, body] unless error.is_a?(Hash)
+
+      [error['code'], error['message'], error['details']]
+    rescue JSON::ParserError
+      [nil, nil, body]
+    end
+
+    def retry_after_of(api_error)
+      headers = api_error.response_headers || {}
+      raw = headers['Retry-After'] || headers['retry-after']
+      raw && Integer(raw, exception: false)
+    end
+  end
+end