sendproof-rails 0.1.0.alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: fd2144b4ee32e4e91fa4ab9e317b35f026f891f8e7d589e0a380cd1e72b4bace
4
+ data.tar.gz: d1ca2ec67e7bced227cb2f3d3b79bd0ebc26726b73f90b72a5e0e5d5c589579a
5
+ SHA512:
6
+ metadata.gz: d8ce639dc9fa0b2e11a0853767f10a6bf02b324a81de51e674d8d29190a1421df0a82ea057ad7df017d2823f5e1314244c5dce7bbde0f8cf2e86daccc52c1251
7
+ data.tar.gz: a04e555cefd1545e9a1c647630a1f51b20f4bd401d378491b813eeae13f19a89368ed842f71c9d4d28bc104cc6496c47f8f0e219f83422d94d59ece31f7b05e7
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sendproof contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,46 @@
1
+ # sendproof-rails
2
+
3
+ Rails engine for [Sendproof](../README.md). Tested with Rails 8.0.5.2 (API mode, cookie sessions, Puma). Discovery also names the binding (`{language: "ruby", framework: "Rails"}`). Data stores: [data-stores.md](../data-stores.md).
4
+
5
+ ```ruby
6
+ # config/initializers/sendproof.rb
7
+ Rails.application.configure do
8
+ config.sendproof.environments = %w[development]
9
+ config.sendproof.api_name = "Inventory" # default: the application class
10
+ config.sendproof.open_api_url = "/openapi.json"
11
+ config.sendproof.auth_provider "Staff", "cookie", "/auth/sign-in"
12
+ config.sendproof.identity = ->(request) { ... } # { name:, role:, subject: } or nil
13
+ config.sendproof.use Sendproof::ActiveRecord::Provider.new
14
+ end
15
+ ```
16
+
17
+ ## Marking actions
18
+
19
+ ```ruby
20
+ class ItemsController < ApplicationController
21
+ sendproof_preview only: %i[create update] # or except: [...], or bare for every action
22
+ end
23
+ ```
24
+
25
+ Mark an action you know writes to a store Sendproof can only guard (Redis, DynamoDB) as `preview: false`, with the reason the workbench shows before anyone tries. Send still works; a Preview of it is refused without running the action:
26
+
27
+ ```ruby
28
+ class SessionsController < ApplicationController
29
+ sendproof_preview only: %i[create update]
30
+ sendproof_no_preview only: :destroy, reason: "Clears the Redis session" # or stores: :redis
31
+ end
32
+ ```
33
+
34
+ Discovery lists the verbs and `{param}` path templates of marked, routed actions, so `previewOperations` always matches the router. Mounted Rack apps are never listed. An unmarked or unknown target is refused (409/404) before any transaction opens.
35
+
36
+ ## How it integrates
37
+
38
+ - The engine appends `Sendproof::Middleware` as the **last** middleware, after cookies, session and authentication middleware and right before the router, so a preview is routed and authenticated like a real call.
39
+ - A hook around `send_action` anchors the preview at the real action, after `before_action` authentication and authorization. A request halted by a filter never reaches it, so it is never confirmed.
40
+ - Framework-handled exceptions that Rails maps to a client error (`RecordNotFound`, `ParameterMissing`, …) become confirmed inner responses; anything that maps to 500 is unconfirmed.
41
+ - `Rails.logger` entries at `config.sendproof.log_level` (default `:info`) and above are copied into the capture through a broadcast sink. SQL appears as structured `Sql` entries instead.
42
+ - The preview's session and cookies are never written to the real response.
43
+
44
+ Observed Send (`Prefer: trace`) needs `identity` to return a `subject`; the trace is readable only by that subject on that mount and expires after `trace_ttl` seconds (default 300).
45
+
46
+ Not included: ActionMailer, ActiveJob and HTTP-client interceptors, OIDC challenge routes.
@@ -0,0 +1,59 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Rails
5
+ # {Sendproof::Configuration} with Rails defaults: the Rails environment, application name,
6
+ # routes-based preview discovery, and Rails' exception-to-status mapping.
7
+ class Configuration < Sendproof::Configuration
8
+ # @return [Symbol] minimum level of Rails.logger entries copied into captures (default :info)
9
+ attr_accessor :log_level
10
+
11
+ def initialize(**options)
12
+ @log_level = :info
13
+ super
14
+ self.logger ||= nil
15
+ end
16
+
17
+ def environment = @environment_override || ::Rails.env.to_s
18
+
19
+ def environment=(value)
20
+ @environment_override = value&.to_s
21
+ end
22
+
23
+ def api_name
24
+ @api_name || ::Rails.application.class.module_parent_name.presence || ::Rails.application.class.name || "API"
25
+ end
26
+
27
+ def logger = @logger || ::Rails.logger
28
+
29
+ def framework = @framework || "Rails"
30
+
31
+ def preview_operations=(operations)
32
+ @preview_operations_set = true
33
+ super
34
+ end
35
+
36
+ def resolve_target(method, path, env)
37
+ return super if @preview_operations_set || target_resolver
38
+
39
+ Routes.resolve(method, path)
40
+ end
41
+
42
+ # Defaults to Rails' own exception-to-status table (rescue_responses). The base class only
43
+ # treats 4xx results as handled client errors; everything else stays an unconfirmed failure.
44
+ def exception_status = @exception_status || Routes.method(:status_for_error)
45
+
46
+ private
47
+
48
+ # Marked operations come from +sendproof_no_preview+ unless set explicitly.
49
+ def unavailable_source
50
+ @preview_unavailable.respond_to?(:call) || !@preview_unavailable.empty? ? super : Routes.unavailable
51
+ end
52
+
53
+ # Operations come from preview-enabled controller actions unless set explicitly.
54
+ def operations_source
55
+ @preview_operations_set ? super : Routes.operations
56
+ end
57
+ end
58
+ end
59
+ end
@@ -0,0 +1,80 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Rails
5
+ # Mixed into ActionController. Marks actions as preview-enabled and anchors the preview at
6
+ # the real action, after the host's before_action chain has authenticated and authorized it.
7
+ #
8
+ # class ItemsController < ApplicationController
9
+ # sendproof_preview only: %i[create update destroy]
10
+ # end
11
+ module Controller
12
+ extend ActiveSupport::Concern
13
+
14
+ included do
15
+ class_attribute :_sendproof_preview, instance_accessor: false, default: nil
16
+ class_attribute :_sendproof_no_preview, instance_accessor: false, default: []
17
+ end
18
+
19
+ class_methods do
20
+ # Enables Sendproof preview and observed send for actions of this controller.
21
+ #
22
+ # Enable only actions whose complete effect stays inside the configured provider's
23
+ # transaction or is recorded through {Sendproof.record_effect}.
24
+ #
25
+ # @param only [Array<Symbol>, nil] enable just these actions
26
+ # @param except [Array<Symbol>, nil] enable every action but these
27
+ def sendproof_preview(only: nil, except: nil)
28
+ self._sendproof_preview = { only: only && Array(only).map(&:to_s), except: Array(except).map(&:to_s) }
29
+ end
30
+
31
+ # Marks actions +preview: false+: the workbench shows "Preview unavailable" with the reason
32
+ # before the user tries, and a Preview of one never runs the action. Use it for an action you
33
+ # know writes to a store Sendproof can only guard, such as Redis or DynamoDB; without the
34
+ # mark the guard decides at run time, which is also safe. Send and observed Send still work.
35
+ #
36
+ # sendproof_no_preview only: :destroy, reason: "Clears the Redis session"
37
+ # sendproof_no_preview only: :destroy, stores: :redis # reason: "Preview unavailable: this operation writes to Redis"
38
+ #
39
+ # @param only [Array<Symbol>, nil] mark just these actions
40
+ # @param except [Array<Symbol>, nil] mark every action but these
41
+ # @param reason [String, nil] shown in the workbench; required unless +stores+ is given
42
+ # @param stores [Array<Symbol>, nil] the store ids the action writes (+:redis+, +:dynamodb+, +:mongodb+)
43
+ def sendproof_no_preview(only: nil, except: nil, reason: nil, stores: nil)
44
+ stores = Array(stores).map(&:to_s)
45
+ text = reason || (stores.empty? ? nil : Sendproof::Stores::Guard.write_reason(stores.first))
46
+ if text.nil? || text.strip.empty? || text.length > 512
47
+ raise ArgumentError, "Give sendproof_no_preview a reason, or the stores the action writes."
48
+ end
49
+
50
+ rule = { only: only && Array(only).map(&:to_s), except: Array(except).map(&:to_s), reason: text, stores: stores }
51
+ self._sendproof_no_preview = _sendproof_no_preview + [rule]
52
+ end
53
+
54
+ # @return [Boolean] whether +action+ is preview-enabled: enabled by {#sendproof_preview} and not
55
+ # marked by {#sendproof_no_preview}
56
+ def sendproof_preview?(action)
57
+ rule = _sendproof_preview or return false
58
+ action = action.to_s
59
+ (rule[:only].nil? || rule[:only].include?(action)) && !rule[:except].include?(action) && sendproof_unavailable(action).nil?
60
+ end
61
+
62
+ # @return [Hash, nil] +{reason:, stores:}+ when +action+ is marked +preview: false+
63
+ def sendproof_unavailable(action)
64
+ action = action.to_s
65
+ rule = _sendproof_no_preview.find { |item| (item[:only].nil? || item[:only].include?(action)) && !item[:except].include?(action) }
66
+ rule && { reason: rule[:reason], stores: rule[:stores] }
67
+ end
68
+ end
69
+
70
+ # Runs the action inside the active preview or observed send. This is the innermost point
71
+ # shared by every controller callback chain: nothing below it runs for a rejected request.
72
+ def send_action(method_name, *args)
73
+ context = request.env[Sendproof::ENV_KEY]
74
+ return super unless context
75
+
76
+ context.around_handler(request: request, eligible: self.class.sendproof_preview?(method_name)) { super }
77
+ end
78
+ end
79
+ end
80
+ end
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Rails
5
+ # The Rails engine. Configure it with +config.sendproof+:
6
+ #
7
+ # config.sendproof.environments = %w[development]
8
+ # config.sendproof.open_api_url = "/openapi.json"
9
+ # config.sendproof.identity = ->(request) { { name: ..., subject: ... } }
10
+ # config.sendproof.use Sendproof::ActiveRecord::Provider.new
11
+ #
12
+ # Nothing is served until +environments+ names the running environment.
13
+ class Engine < ::Rails::Engine
14
+ config.sendproof = Sendproof::Rails::Configuration.new
15
+
16
+ initializer "sendproof.controller_hook" do
17
+ ActiveSupport.on_load(:action_controller) { include Sendproof::Rails::Controller }
18
+ end
19
+
20
+ # Last in the stack: sessions, cookies and authentication middleware have already run, and
21
+ # the next hop is the router, so a preview is routed and authorized exactly like a real call.
22
+ initializer "sendproof.middleware" do |app|
23
+ app.middleware.use Sendproof::Middleware, app.config.sendproof
24
+ end
25
+
26
+ initializer "sendproof.logging" do |app|
27
+ Sendproof::Rails::LogSink.attach(app.config.sendproof)
28
+ end
29
+ end
30
+ end
31
+ end
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "logger"
4
+
5
+ module Sendproof
6
+ module Rails
7
+ # A logger that copies Rails.logger entries into the active capture.
8
+ # It is attached by broadcast, so existing log destinations are unchanged.
9
+ class LogSink < ::Logger
10
+ LEVELS = { DEBUG => "Debug", INFO => "Information", WARN => "Warning", ERROR => "Error",
11
+ FATAL => "Critical", UNKNOWN => "Information" }.freeze
12
+
13
+ # Attaches a sink to Rails.logger when the workbench is enabled and the logger can broadcast.
14
+ def self.attach(config)
15
+ return unless config.enabled?
16
+
17
+ logger = ::Rails.logger
18
+ return unless logger.respond_to?(:broadcast_to)
19
+
20
+ sink = new(nil)
21
+ sink.level = config.log_level
22
+ logger.broadcast_to(sink)
23
+ end
24
+
25
+ def add(severity, message = nil, progname = nil)
26
+ severity ||= UNKNOWN
27
+ return true if severity < level
28
+
29
+ recorder = Sendproof::Capture.current or return true
30
+ # Logger#info("text") passes the text as the progname; with a block, progname is the category.
31
+ if message.nil?
32
+ message = block_given? ? yield : progname
33
+ progname = nil if !block_given?
34
+ end
35
+ error = message if message.is_a?(Exception)
36
+ text = error ? "#{error.class}: #{error.message}" : message.to_s
37
+ recorder.log(level: LEVELS.fetch(severity, "Information"), message: text.strip, exception: error,
38
+ category: progname.is_a?(String) ? progname : nil)
39
+ true
40
+ end
41
+ end
42
+ end
43
+ end
@@ -0,0 +1,62 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Rails
5
+ # Reads preview eligibility from the application's router.
6
+ module Routes
7
+ FORMAT = /\(\.:format\)\z/
8
+
9
+ module_function
10
+
11
+ # @return [Array<Array(String, String)>] +[verb, OpenAPI path template]+ for every preview-enabled route
12
+ def operations
13
+ ::Rails.application.routes.routes.flat_map do |route|
14
+ next [] unless route.dispatcher? && (controller = controller_class(route.defaults[:controller]))
15
+ next [] unless controller.respond_to?(:sendproof_preview?) && controller.sendproof_preview?(route.defaults[:action])
16
+
17
+ verbs(route).map { |verb| [verb, template(route.path.spec.to_s)] }
18
+ end
19
+ end
20
+
21
+ # @return [Array<Hash>] +{method:, path:, reason:, stores:}+ for every route marked +preview: false+
22
+ def unavailable
23
+ ::Rails.application.routes.routes.flat_map do |route|
24
+ next [] unless route.dispatcher? && (controller = controller_class(route.defaults[:controller]))
25
+ next [] unless controller.respond_to?(:sendproof_unavailable)
26
+
27
+ mark = controller.sendproof_unavailable(route.defaults[:action]) or next []
28
+ verbs(route).map { |verb| { method: verb, path: template(route.path.spec.to_s), **mark } }
29
+ end
30
+ end
31
+
32
+ # @return [Symbol, nil] +:eligible+, +:ineligible+, or nil when the router has no such endpoint
33
+ def resolve(method, path)
34
+ params = ::Rails.application.routes.recognize_path(path, method: method)
35
+ controller = controller_class(params[:controller])
36
+ return :ineligible unless controller.respond_to?(:sendproof_preview?)
37
+
38
+ controller.sendproof_preview?(params[:action]) ? :eligible : :ineligible
39
+ rescue ::ActionController::RoutingError
40
+ nil
41
+ end
42
+
43
+ # Handled client errors (RecordNotFound, ParameterMissing, ...) become inner responses, as ShowExceptions would.
44
+ def status_for_error(error)
45
+ ::ActionDispatch::ExceptionWrapper.status_code_for_exception(error.class.name)
46
+ end
47
+
48
+ def controller_class(name)
49
+ name && "#{name.camelize}Controller".safe_constantize
50
+ end
51
+
52
+ def verbs(route)
53
+ route.verb.to_s.split("|").reject { |verb| verb == "HEAD" }
54
+ end
55
+
56
+ # +/items/:id(.:format)+ becomes +/items/{id}+; optional groups are dropped.
57
+ def template(spec)
58
+ spec.sub(FORMAT, "").gsub(/\([^()]*\)/, "").gsub(/[:*]([a-z_][a-zA-Z0-9_]*)/, '{\1}')
59
+ end
60
+ end
61
+ end
62
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "rails"
4
+ require "action_controller/railtie"
5
+ require "sendproof"
6
+
7
+ module Sendproof
8
+ # Rails integration: a Railtie that mounts the workbench, discovers preview-enabled
9
+ # controller actions from the router, and anchors preview transactions at the real action.
10
+ module Rails
11
+ autoload :Configuration, "sendproof/rails/configuration"
12
+ autoload :Controller, "sendproof/rails/controller"
13
+ autoload :LogSink, "sendproof/rails/log_sink"
14
+ autoload :Routes, "sendproof/rails/routes"
15
+ end
16
+ end
17
+
18
+ require "sendproof/rails/engine"
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "sendproof/rails"
metadata ADDED
@@ -0,0 +1,108 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: sendproof-rails
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0.alpha.1
5
+ platform: ruby
6
+ authors:
7
+ - Sendproof contributors
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 2026-11-22 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: sendproof-core
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - '='
17
+ - !ruby/object:Gem::Version
18
+ version: 0.1.0.alpha.1
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - '='
24
+ - !ruby/object:Gem::Version
25
+ version: 0.1.0.alpha.1
26
+ - !ruby/object:Gem::Dependency
27
+ name: railties
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '8.0'
33
+ - - "<"
34
+ - !ruby/object:Gem::Version
35
+ version: '9'
36
+ type: :runtime
37
+ prerelease: false
38
+ version_requirements: !ruby/object:Gem::Requirement
39
+ requirements:
40
+ - - ">="
41
+ - !ruby/object:Gem::Version
42
+ version: '8.0'
43
+ - - "<"
44
+ - !ruby/object:Gem::Version
45
+ version: '9'
46
+ - !ruby/object:Gem::Dependency
47
+ name: actionpack
48
+ requirement: !ruby/object:Gem::Requirement
49
+ requirements:
50
+ - - ">="
51
+ - !ruby/object:Gem::Version
52
+ version: '8.0'
53
+ - - "<"
54
+ - !ruby/object:Gem::Version
55
+ version: '9'
56
+ type: :runtime
57
+ prerelease: false
58
+ version_requirements: !ruby/object:Gem::Requirement
59
+ requirements:
60
+ - - ">="
61
+ - !ruby/object:Gem::Version
62
+ version: '8.0'
63
+ - - "<"
64
+ - !ruby/object:Gem::Version
65
+ version: '9'
66
+ description: Adds the workbench at /sendproof, discovers preview-enabled controller
67
+ actions from the router, and dispatches previews through the application's real
68
+ middleware and controllers.
69
+ executables: []
70
+ extensions: []
71
+ extra_rdoc_files: []
72
+ files:
73
+ - LICENSE
74
+ - README.md
75
+ - lib/sendproof-rails.rb
76
+ - lib/sendproof/rails.rb
77
+ - lib/sendproof/rails/configuration.rb
78
+ - lib/sendproof/rails/controller.rb
79
+ - lib/sendproof/rails/engine.rb
80
+ - lib/sendproof/rails/log_sink.rb
81
+ - lib/sendproof/rails/routes.rb
82
+ homepage: https://github.com/mprync/sendproof
83
+ licenses:
84
+ - MIT
85
+ metadata:
86
+ source_code_uri: https://github.com/mprync/sendproof
87
+ bug_tracker_uri: https://github.com/mprync/sendproof/issues
88
+ changelog_uri: https://github.com/mprync/sendproof/releases
89
+ documentation_uri: https://github.com/mprync/sendproof/tree/main/adapters/ruby#readme
90
+ rubygems_mfa_required: 'true'
91
+ rdoc_options: []
92
+ require_paths:
93
+ - lib
94
+ required_ruby_version: !ruby/object:Gem::Requirement
95
+ requirements:
96
+ - - ">="
97
+ - !ruby/object:Gem::Version
98
+ version: '3.3'
99
+ required_rubygems_version: !ruby/object:Gem::Requirement
100
+ requirements:
101
+ - - ">="
102
+ - !ruby/object:Gem::Version
103
+ version: '0'
104
+ requirements: []
105
+ rubygems_version: 3.6.9
106
+ specification_version: 4
107
+ summary: Rails engine that mounts the Sendproof workbench inside a Rails API.
108
+ test_files: []