riffer 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 491260200757bf1d17b920f099012d771328fd333d46bb325f53dca863bcf204
-  data.tar.gz: 072ffcdf47b2aa115a3c7743cb77d4f238d18b926f0a53eb6b45a28148b8b2be
+  metadata.gz: cf3c522a083d44f9aff259baf496cea4f6da7a160872b1e78a2f123693a19942
+  data.tar.gz: b3220efe62fcb3144fdc041f71c914baff02003b5f1aad3b4af285487986c673
 SHA512:
-  metadata.gz: 97bf5aeed05fe9b591ae5a2bcf7c59d6990a46de1695fa4ff929823ead08b23372f35c4efb389a7e2f769a2a15dbad4dcb35bb1421e57c1fe5291216390b176c
-  data.tar.gz: 421d381a7d8c0a1be0c017a2c347096fa452d48d512706c474e82b5d90097e245d9f7680ed6745c10aac31502cdfe47efc56ae885dbd9e4b52b3b7e2803b7c10
+  metadata.gz: 82ca97fe33585a833f6126837c9546ee137aa2ccc0259f732a7f634207e82f3fa0c4a4ec05f80274c73fefa9e234c27b63db87672df1198412c6b66a9884b564
+  data.tar.gz: b91541b19e44d4a02efbf10cd6bda8b3476fbf846f61e2cdabe19822fc1648542a2279ec4170e8dcc2ff462bc1419af552237e6f8e47e2748949139a5b53b9b2

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.36.0"
+  ".": "0.37.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.37.0](https://github.com/janeapp/riffer/compare/riffer/v0.36.0...riffer/v0.37.0) (2026-07-10)
+
+
+### Features
+
+* **providers:** first-class provider registration API ([#353](https://github.com/janeapp/riffer/issues/353)) ([551d80b](https://github.com/janeapp/riffer/commit/551d80bf615de813629768156c6674d232877150))
+
 ## [0.36.0](https://github.com/janeapp/riffer/compare/riffer/v0.35.0...riffer/v0.36.0) (2026-07-03)
 
 

data/docs/providers/07_CUSTOM_PROVIDERS.md

@@ -137,30 +137,15 @@ end
 
 ## Registering Your Provider
 
-Add your provider to the repository:
+Register your provider under an identifier.
 
 ```ruby
-# In lib/riffer/providers/repository.rb or your own code
-
-Riffer::Providers::Repository::REPO[:my_provider] = -> { Riffer::Providers::MyProvider }
+Riffer::Providers::Repository.register(:my_provider) { Riffer::Providers::MyProvider }
 ```
 
-Or create a custom repository:
+The block resolves the provider class lazily, so it need not be loaded at registration time. Registration is idempotent — re-registering the same identifier replaces the previous factory — and a custom registration takes precedence over a built-in sharing the identifier, which lets you route an existing prefix (e.g. `openai`) through your own backend. Both `find` and `key_for` (used for pricing and observability keys) honor the registration. Remove one with `Riffer::Providers::Repository.unregister(:my_provider)`.
 
-```ruby
-module MyApp
-  module Providers
-    def self.find(identifier)
-      case identifier.to_sym
-      when :my_provider
-        Riffer::Providers::MyProvider
-      else
-        Riffer::Providers::Repository.find(identifier)
-      end
-    end
-  end
-end
-```
+Register during application boot — from a Rails initializer or equivalent — before you start handling requests. The registry is not synchronized for concurrent mutation, so treat registration as a one-time setup step rather than something you do from a live request path.
 
 ## Using Your Provider
 

data/lib/riffer/providers/repository.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Registry for finding provider classes by identifier.
+# Resolves provider classes by identifier, combining the built-in REPO with
+# consumer registrations added through +register+. Registration is not
+# synchronized — register during boot, before concurrent generation begins.
 module Riffer::Providers::Repository
   extend self
 
+  # @rbs @registrations: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
   # @rbs @key_for: Hash[singleton(Riffer::Providers::Base), Symbol]?
 
   REPO = {
@@ -17,18 +20,55 @@ module Riffer::Providers::Repository
     mock: -> { Riffer::Providers::Mock }
   }.freeze #: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
-  # Finds a provider class by identifier.
+  @registrations = {} #: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
+
+  # Registers a custom provider under +identifier+, resolved lazily by the block.
+  # Takes precedence over a built-in sharing the identifier.
+  #
+  #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
+  #
+  # Raises Riffer::ArgumentError when called without a block.
+  #
+  #--
+  #: ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
+  def register(identifier, &factory)
+    raise Riffer::ArgumentError, "register requires a block returning a provider class" unless factory
+
+    @registrations[identifier.to_sym] = factory
+    @key_for = nil
+  end
+
+  # Removes a custom registration by identifier, leaving any built-in of the
+  # same name intact.
+  #--
+  #: ((String | Symbol)) -> void
+  def unregister(identifier)
+    @registrations.delete(identifier.to_sym)
+    @key_for = nil
+  end
+
+  # Finds a provider class by identifier, preferring a custom registration over
+  # a built-in of the same name.
   #
   #--
   #: ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
   def find(identifier)
-    REPO.fetch(identifier.to_sym, nil)&.call
+    key = identifier.to_sym
+    (@registrations[key] || REPO[key])&.call
   end
 
   # Returns the registry identifier for a provider class, or nil when unregistered.
   #--
   #: (singleton(Riffer::Providers::Base)) -> Symbol?
   def key_for(provider_class)
-    (@key_for ||= REPO.to_h { |key, factory| [factory.call, key] })[provider_class]
+    (@key_for ||= build_key_index)[provider_class]
+  end
+
+  private
+
+  #--
+  #: () -> Hash[singleton(Riffer::Providers::Base), Symbol]
+  def build_key_index
+    REPO.merge(@registrations).to_h { |key, factory| [factory.call, key] }
   end
 end

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.36.0" #: String
+  VERSION = "0.37.0" #: String
 end

data/sig/generated/riffer/providers/repository.rbs

@@ -1,12 +1,34 @@
 # Generated from lib/riffer/providers/repository.rb with RBS::Inline
 
-# Registry for finding provider classes by identifier.
+# Resolves provider classes by identifier, combining the built-in REPO with
+# consumer registrations added through +register+. Registration is not
+# synchronized — register during boot, before concurrent generation begins.
 module Riffer::Providers::Repository
+  @registrations: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
+
   @key_for: Hash[singleton(Riffer::Providers::Base), Symbol]?
 
   REPO: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
-  # Finds a provider class by identifier.
+  # Registers a custom provider under +identifier+, resolved lazily by the block.
+  # Takes precedence over a built-in sharing the identifier.
+  #
+  #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
+  #
+  # Raises Riffer::ArgumentError when called without a block.
+  #
+  # --
+  # : ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
+  def register: (String | Symbol) { () -> singleton(Riffer::Providers::Base) } -> void
+
+  # Removes a custom registration by identifier, leaving any built-in of the
+  # same name intact.
+  # --
+  # : ((String | Symbol)) -> void
+  def unregister: (String | Symbol) -> void
+
+  # Finds a provider class by identifier, preferring a custom registration over
+  # a built-in of the same name.
   #
   # --
   # : ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
@@ -16,4 +38,10 @@ module Riffer::Providers::Repository
   # --
   # : (singleton(Riffer::Providers::Base)) -> Symbol?
   def key_for: (singleton(Riffer::Providers::Base)) -> Symbol?
+
+  private
+
+  # --
+  # : () -> Hash[singleton(Riffer::Providers::Base), Symbol]
+  def build_key_index: () -> Hash[singleton(Riffer::Providers::Base), Symbol]
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.51.0
+        version: 1.55.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.51.0
+        version: 1.55.0
 - !ruby/object:Gem::Dependency
   name: aws-sdk-bedrockruntime
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +108,7 @@ dependencies:
         version: '2.25'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.42'
+        version: '2.43'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -118,21 +118,21 @@ dependencies:
         version: '2.25'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.42'
+        version: '2.43'
 - !ruby/object:Gem::Dependency
   name: io-event
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '1.20'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '1.20'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement