rapitapir 2.0.0 → 2.1.0

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.
Files changed (63) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop_todo.yml +5 -0
  3. data/CHANGELOG.md +29 -1
  4. data/README.md +23 -4
  5. data/RUBY_WEEKLY_LAUNCH_POST.md +43 -62
  6. data/docs/adr/0001-base-class-strategy.md +33 -0
  7. data/docs/adr/0002-type-shortcut-and-type-system.md +30 -0
  8. data/docs/adr/0003-openapi-source-of-truth.md +32 -0
  9. data/docs/adr/0004-client-generation-typescript-first.md +34 -0
  10. data/docs/adr/0005-auth-architecture.md +32 -0
  11. data/docs/adr/0006-observability-defaults.md +30 -0
  12. data/docs/adr/0007-ai-scope-and-boundaries.md +30 -0
  13. data/docs/adr/README.md +46 -0
  14. data/docs/adr/template.md +24 -0
  15. data/docs/blueprint.md +92 -4
  16. data/docs/implementation-status.md +1 -1
  17. data/examples/auto_derivation_ruby_friendly.rb +44 -113
  18. data/examples/cli/user_api_endpoints.rb +63 -36
  19. data/examples/demo_api.rb +57 -18
  20. data/examples/enterprise_extension_demo.rb +13 -13
  21. data/examples/enterprise_rapitapir_api.rb +81 -93
  22. data/examples/nocodb/nocodb_scaffold/Gemfile +22 -0
  23. data/examples/nocodb/nocodb_scaffold/README.md +10 -0
  24. data/examples/nocodb/nocodb_scaffold/Rakefile +7 -0
  25. data/examples/nocodb/nocodb_scaffold/app/api/app.rb +1139 -0
  26. data/examples/nocodb/nocodb_scaffold/app/models/email_template.rb +6 -0
  27. data/examples/nocodb/nocodb_scaffold/app/models/faq.rb +6 -0
  28. data/examples/nocodb/nocodb_scaffold/app/models/feature.rb +6 -0
  29. data/examples/nocodb/nocodb_scaffold/app/models/idea.rb +6 -0
  30. data/examples/nocodb/nocodb_scaffold/app/models/itinerary_day.rb +6 -0
  31. data/examples/nocodb/nocodb_scaffold/app/models/route.rb +6 -0
  32. data/examples/nocodb/nocodb_scaffold/app/models/subscriber.rb +6 -0
  33. data/examples/nocodb/nocodb_scaffold/app/models/tour.rb +6 -0
  34. data/examples/nocodb/nocodb_scaffold/app/models/webhook.rb +6 -0
  35. data/examples/nocodb/nocodb_scaffold/app/models_loader.rb +3 -0
  36. data/examples/nocodb/nocodb_scaffold/config/database.yml +11 -0
  37. data/examples/nocodb/nocodb_scaffold/config.ru +9 -0
  38. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152012_create_features.rb +10 -0
  39. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152013_create_tours.rb +10 -0
  40. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152014_create_routes.rb +10 -0
  41. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152015_create_itinerary_days.rb +10 -0
  42. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152016_create_subscribers.rb +10 -0
  43. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152017_create_email_templates.rb +10 -0
  44. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152018_create_faqs.rb +10 -0
  45. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152019_create_webhooks.rb +10 -0
  46. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152020_create_ideas.rb +10 -0
  47. data/examples/nocodb/swagger.json +4378 -0
  48. data/examples/production_ready_example.rb +78 -58
  49. data/examples/simple_demo_api.rb +40 -7
  50. data/examples/user_api.rb +130 -132
  51. data/lib/rapitapir/auth/oauth2.rb +1 -1
  52. data/lib/rapitapir/cli/command.rb +30 -4
  53. data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
  54. data/lib/rapitapir/cli/validator.rb +1 -1
  55. data/lib/rapitapir/core/enhanced_endpoint.rb +1 -1
  56. data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
  57. data/lib/rapitapir/openapi/schema_generator.rb +46 -2
  58. data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
  59. data/lib/rapitapir/server/middleware.rb +2 -2
  60. data/lib/rapitapir/types/auto_derivation.rb +2 -4
  61. data/lib/rapitapir/version.rb +1 -1
  62. data/rapitapir.gemspec +3 -2
  63. metadata +70 -8
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: deccb0d6ca9e591e3a2fab10940b4e177181fff12c6067297871388d33d5ce3e
4
- data.tar.gz: 0f14ea824545c131ac9c45bcb5616a0b587de17d202a5050abaadbc7a4e044f8
3
+ metadata.gz: 6d2520e4b24ee5927e01f130de108a554b6b820f0cb501160e129dc054852320
4
+ data.tar.gz: 0ffafcc50aeb89b89ab477dbc252fcd8a5352d51134960ac92ee02053bc6b7e3
5
5
  SHA512:
6
- metadata.gz: d32fd597c0a5713999afa77a1e49d17899b23e9c1b1e5aeefded0690e7031a174b842f0147f2a6bce9755c6ebacdbe9b9be50d1c89c286f1c4cdf4689c8ab7d5
7
- data.tar.gz: 1315df6e9d3797452453a990a6160244edea18175d9af913faf08494c9c7c5e154e6a5989a5979bdc2ad4c94f5eefb80a38863cf3ec6f2f76e63ec73177314a2
6
+ metadata.gz: fd644750fd860960c7e0b78af2ef56d60b8ffbfc575d65f22937f8e2c1de3a4907898b7ba62711d4a27baaa2497f3dd9052c0547fbc30f06d7c6d4c107f56b2d
7
+ data.tar.gz: 1ef21dc5edb5a112e91a0e9ce0be85b8894d380a1877714ab1cd1578185fed5d2ccc0e76d25734910eabebd41c6392d6e95a0bdb7b94dffa93a6b7e7207b8520
data/.rubocop_todo.yml CHANGED
@@ -81,3 +81,8 @@ Style/OpenStructUse:
81
81
  Style/SafeNavigationChainLength:
82
82
  Exclude:
83
83
  - 'lib/rapitapir/ai/mcp.rb'
84
+
85
+ # Top-level String monkey-patch for pluralization/singularization
86
+ Style/OneClassPerFile:
87
+ Exclude:
88
+ - 'lib/rapitapir/sinatra/resource_builder.rb'
data/CHANGELOG.md CHANGED
@@ -1,10 +1,38 @@
1
1
  # Changelog
2
2
 
3
- All- 📏 **Type Shortcuts**: Global `T` constant for cleaner type syntax (automatically available - no setup needed)notable changes to this project will be documented in this file.
3
+ All notable changes to this project will be documented in this file.
4
4
 
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.1.0] - 2026-11-22
9
+
10
+ ### Summary
11
+ Dependency refresh to the latest gem releases, with code adaptations for
12
+ breaking API changes, and a full repair of the example catalog.
13
+
14
+ ### Added
15
+ - 📦 **jwt runtime dependency declared in the gemspec** (`>= 2.10, < 4.0`) — it was lazily `require`d by `RapiTapir::Auth` OAuth2 validation but never declared, so installs could silently lack it
16
+
17
+ ### Changed
18
+ - 🔢 **Bumped all dependencies to their latest releases**: dotenv 3.2, json 3.1, jwt 3.3, rack 3.2, puma 8.1, simplecov 1.3, sinatra 4.2, webmock 3.38, rubocop 1.92, rackup 2.3, rack-test 2.3, rspec 3.13, webrick 1.9, OpenTelemetry exporter-otlp 0.37 / instrumentation-all 0.102 / sdk 1.13
19
+ - 🐾 **Minimum Ruby raised to 3.3** (`required_ruby_version >= 3.3`). The latest OpenTelemetry stack (api 1.9+, sdk 1.11+, common 0.24+) declares `ruby >= 3.3`; keeping the current otel releases required dropping the EOL 3.1/3.2 runtimes. CI matrix and all workflows now test 3.3/3.4. **This is a breaking change for Ruby 3.1/3.2 users.**
20
+ - ⬆️ **json range widened in the gemspec** to `>= 2.6, < 4.0` to match the refreshed stack
21
+ - 🧩 **JWT v3 compatibility**: `JWT.decode` no longer accepts the positional `verify` argument — replaced with the `verify_signature: true` option (works on jwt ≥ 2.10 and 3.x)
22
+ - 🎨 **RuboCop 1.92 compliance**: `Style/DirectiveScope` disable/enable pairs converted to `disable-next`
23
+
24
+ ### Fixed
25
+ - 📚 **`examples/enterprise_rapitapir_api.rb`**: `configure`/`set` were called from an instance `initialize` (crash on boot); auth/middleware setup moved to class level; `SinatraAdapter` now binds to the app class (Sinatra 4 removed instance→class delegation); handlers use the adapter's `[status, headers, body]` response protocol
26
+ - 📚 **`examples/enterprise_extension_demo.rb`**: `bearer_auth` → `add_auth_scheme(:bearer, RapiTapir::Auth.bearer_token(...))` (the real `Configuration` API)
27
+ - 📚 **`examples/demo_api.rb`, `simple_demo_api.rb`, `cli/user_api_endpoints.rb`, `user_api.rb`, `production_ready_example.rb`**: rewritten from the removed `.in/.out/.error_out` DSL onto the current builder (`json_body`, `ok`, `created`, `no_content`, `not_found`, …) with proper `RapiTapir::Types.hash/array` types
28
+ - 📚 **`examples/auto_derivation_ruby_friendly.rb`**: now demos only the real derivation APIs (`from_hash`, `from_open_struct`, `from_json_schema`, `from_protobuf`)
29
+ - 🧪 **All 18 examples verified running**, including live HTTP checks of the three server examples
30
+
31
+ ### Verification
32
+ - ✅ 695 RSpec examples, 0 failures
33
+ - ✅ RuboCop: 91 files, no offenses
34
+ - ✅ `gem build` produces a clean installable package
35
+
8
36
  ## [Unreleased] - 2025-08-02
9
37
 
10
38
  ### Summary
data/README.md CHANGED
@@ -1,8 +1,9 @@
1
1
  # RapiTapir
2
2
 
3
- [![Tests](https://img.shields.io/badge/tests-643%20passing-brightgreen)](spec/)
4
- [![Coverage](https://img.shields.io/badge/coverage-67.67%25-green)](coverage/)
5
- [![Ruby](https://img.shields.io/badge/ruby-3.1%2B-red)](Gemfile)
3
+ [![Tests](https://img.shields.io/badge/tests-695%20passing-brightgreen)](spec/)
4
+ [![Coverage](https://img.shields.io/badge/coverage-72.7%25-green)](coverage/)
5
+ [![Branches](https://img.shields.io/badge/branches-44.89%25-yellow)](coverage/)
6
+ [![Ruby](https://img.shields.io/badge/ruby-3.3%2B-red)](Gemfile)
6
7
  [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
7
8
  [![RuboCop](https://img.shields.io/badge/code%20style-rubocop-brightgreen)](https://github.com/rubocop/rubocop)
8
9
  [![AI Ready](https://img.shields.io/badge/AI-LLM%20%7C%20RAG%20%7C%20MCP-purple)](lib/rapitapir/ai/)
@@ -18,7 +19,7 @@
18
19
  - **⚡ T Shortcut**: Use `T.string` instead of `RapiTapir::Types.string` everywhere
19
20
  - **📚 GitHub Pages Ready**: Modern documentation deployment with GitHub Actions
20
21
  - **🔍 CLI Toolkit**: Complete command-line interface for generation, validation, and serving
21
- - **🧪 Comprehensive Tests**: 643 tests passing with 67.67% coverage
22
+ - **🧪 Comprehensive Tests**: 695 examples, 0 failures; 72.7% coverage
22
23
 
23
24
  ## ✨ Why RapiTapir?
24
25
 
@@ -1388,6 +1389,24 @@ Explore our comprehensive examples directory:
1388
1389
  - **[Observability Setup](examples/observability/)** - Monitoring and health checks
1389
1390
  - **[CLI Examples](examples/cli/)** - Command-line toolkit usage
1390
1391
 
1392
+ ## Architecture Decision Records (ADRs)
1393
+
1394
+ Key architectural decisions are tracked in `docs/adr/`:
1395
+
1396
+ - ADR index and guidelines: [docs/adr/README.md](docs/adr/README.md)
1397
+ - Template: [docs/adr/template.md](docs/adr/template.md)
1398
+
1399
+ Initial ADRs:
1400
+
1401
+ - [ADR-0001: Base class strategy (SinatraRapiTapir) vs manual extension](docs/adr/0001-base-class-strategy.md)
1402
+ - [ADR-0002: Type shortcut (T) and type system boundaries](docs/adr/0002-type-shortcut-and-type-system.md)
1403
+ - [ADR-0003: OpenAPI source-of-truth and doc generation flow](docs/adr/0003-openapi-source-of-truth.md)
1404
+ - [ADR-0004: Client generation target (TypeScript first) and interface conventions](docs/adr/0004-client-generation-typescript-first.md)
1405
+ - [ADR-0005: Authentication architecture (schemes + helpers + middleware)](docs/adr/0005-auth-architecture.md)
1406
+ - [ADR-0006: Observability defaults (health, logging, metrics/tracing hooks)](docs/adr/0006-observability-defaults.md)
1407
+ - [ADR-0007: AI features scope (RAG/LLM/MCP) and maintainability boundaries](docs/adr/0007-ai-scope-and-boundaries.md)
1408
+
1409
+
1391
1410
  ## 🛠️ CLI Development Toolkit
1392
1411
 
1393
1412
  RapiTapir includes a powerful CLI for streamlined development:
@@ -1,6 +1,6 @@
1
1
  # 🦙 Introducing RapiTapir: Type-Safe HTTP APIs for Ruby
2
2
 
3
- **TL;DR**: RapiTapir brings Scala Tapir's elegance to Ruby with type-safe API development, automatic OpenAPI docs, and a clean DSL that makes building production APIs a joy.
3
+ TL;DR: RapiTapir brings Tapir-style, declarative, type-safe APIs to Ruby with a clean DSL, automatic OpenAPI docs, a TypeScript client, and a new one-command scaffold from an OpenAPI spec.
4
4
 
5
5
  ## The Problem: Ruby API Development Pain Points
6
6
 
@@ -15,21 +15,20 @@ What if we could have the type safety of languages like Scala while keeping Ruby
15
15
 
16
16
  ## Enter RapiTapir 🦙
17
17
 
18
- RapiTapir is inspired by [Scala's Tapir](https://github.com/softwaremill/tapir) library, bringing **declarative, type-safe API development** to Ruby. Define your endpoints once with strong typing, and get automatic validation, documentation, and client generation.
18
+ RapiTapir is inspired by [Scala's Tapir](https://github.com/softwaremill/tapir), bringing **declarative, type-safe API development** to Ruby. Define your endpoints once with strong typing, and get automatic validation, documentation, and client generation.
19
19
 
20
20
  ### The Magic: Clean Base Class Syntax
21
21
 
22
22
  ```ruby
23
23
  require 'rapitapir'
24
24
 
25
- class BookAPI < SinatraRapiTapir
26
- # 🎯 Configure once, get everything
25
+ class BookAPI < RapiTapir::SinatraRapiTapir
27
26
  rapitapir do
28
27
  info(title: 'Book API', version: '1.0.0')
29
- development_defaults! # Auto CORS, docs, health checks
28
+ development_defaults! # health checks, CORS, docs
30
29
  end
31
30
 
32
- # 📏 T shortcut available globally - no imports needed!
31
+ # T shortcut available globally
33
32
  BOOK_SCHEMA = T.hash({
34
33
  "id" => T.integer,
35
34
  "title" => T.string(min_length: 1, max_length: 255),
@@ -39,22 +38,18 @@ class BookAPI < SinatraRapiTapir
39
38
  "pages" => T.optional(T.integer(minimum: 1))
40
39
  })
41
40
 
42
- # 🚀 Fluent endpoint definition with automatic validation
43
41
  endpoint(
44
42
  GET('/books')
45
- .query(:limit, T.optional(T.integer(min: 1, max: 100)))
43
+ .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)))
46
44
  .query(:genre, T.optional(T.string))
47
45
  .summary('List books with filtering')
48
46
  .ok(T.array(BOOK_SCHEMA))
49
47
  .build
50
48
  ) do |inputs|
51
- # inputs are already validated and type-coerced!
52
49
  Book.where(genre: inputs[:genre])
53
50
  .limit(inputs[:limit] || 20)
54
51
  .map(&:to_h)
55
52
  end
56
-
57
- run! if __FILE__ == $0
58
53
  end
59
54
  ```
60
55
 
@@ -76,17 +71,12 @@ end
76
71
  ```ruby
77
72
  # Define once, use everywhere
78
73
  USER_SCHEMA = T.hash({
79
- "email" => T.email, # Built-in email validation
80
- "age" => T.optional(T.integer(min: 0, max: 150)),
81
- "preferences" => T.hash({
82
- "newsletter" => T.boolean,
83
- "theme" => T.enum(['light', 'dark'])
84
- })
74
+ "email" => T.email, # built-in email validation
75
+ "age" => T.optional(T.integer(minimum: 0, maximum: 150))
85
76
  })
86
77
 
87
78
  # Automatic validation + coercion
88
79
  endpoint(POST('/users').json_body(USER_SCHEMA).build) do |inputs|
89
- # inputs[:body] is guaranteed to match USER_SCHEMA
90
80
  User.create(inputs[:body])
91
81
  end
92
82
  ```
@@ -110,37 +100,32 @@ api_resource '/books', schema: BOOK_SCHEMA do
110
100
  end
111
101
  ```
112
102
 
113
- ## Production-Ready Features 🛡️
103
+ ## From OpenAPI to Running App (Scaffold)
114
104
 
115
- ### Built-in Security & Auth
116
- ```ruby
117
- class SecureAPI < SinatraRapiTapir
118
- rapitapir do
119
- bearer_auth :api_key
120
- production_defaults! # Security headers, rate limiting, etc.
121
- end
105
+ Input: an OpenAPI/Swagger JSON.
122
106
 
123
- endpoint(
124
- GET('/admin/users')
125
- .bearer_auth(scopes: ['admin']) # Scope-based authorization
126
- .ok(T.array(USER_SCHEMA))
127
- .build
128
- ) do
129
- require_scope!('admin')
130
- User.all
131
- end
132
- end
133
- ```
107
+ Output: a runnable SinatraRapiTapir + ActiveRecord + SQLite app with:
108
+ - config.ru, Rakefile, Gemfile
109
+ - app/api/app.rb (endpoints mapped; docs, tags, descriptions, and security reflected)
110
+ - app/models, db/migrate, config/database.yml
111
+ - health check and docs enabled by default
134
112
 
135
- ### Observability Out of the Box
136
- ```ruby
137
- rapitapir do
138
- enable_health_checks # GET /health
139
- enable_metrics # Prometheus metrics at /metrics
140
- enable_tracing # OpenTelemetry integration
141
- end
113
+ Try it:
114
+
115
+ ```bash
116
+ rapitapir generate scaffold --from openapi.json --out ./my_api
117
+ cd my_api
118
+ bundle install
119
+ bundle exec rake db:create db:migrate
120
+ bundle exec rackup
142
121
  ```
143
122
 
123
+ ## Production-Ready Features 🛡️
124
+
125
+ - Development defaults: health checks, CORS, and docs out of the box.
126
+ - Security headers: header-based API keys in your OpenAPI are scaffolded and reflected in docs.
127
+ - Observability: health endpoint enabled; metrics/tracing integration planned.
128
+
144
129
  ## Real-World Benefits
145
130
 
146
131
  **🚀 Development Speed**: Define endpoints declaratively, get validation + docs for free
@@ -159,16 +144,10 @@ Works with your existing Ruby stack:
159
144
 
160
145
  ```ruby
161
146
  # Sinatra (recommended) - clean inheritance
162
- class API < SinatraRapiTapir; end
147
+ class API < RapiTapir::SinatraRapiTapir; end
163
148
 
164
- # Sinatra extension
149
+ # Sinatra extension
165
150
  register RapiTapir::Sinatra::Extension
166
-
167
- # Plain Rack
168
- use RapiTapir::Server::RackAdapter
169
-
170
- # Rails controllers (coming soon)
171
- include RapiTapir::Rails::Controller
172
151
  ```
173
152
 
174
153
  ## The Ruby Community Connection
@@ -193,24 +172,26 @@ Or add to your Gemfile:
193
172
  gem 'rapitapir'
194
173
  ```
195
174
 
196
- Check out the [comprehensive examples](https://github.com/riccardomerolla/rapitapir/tree/main/examples) and [documentation](https://riccardomerolla.github.io/rapitapir).
175
+ Check out the examples and docs:
176
+ - Examples: https://github.com/riccardomerolla/rapitapir/tree/main/examples
177
+ - Docs: https://riccardomerolla.github.io/rapitapir
197
178
 
198
- ## What's Next?
179
+ ## What’s Next?
199
180
 
200
- - 🎯 **Rails integration** for seamless adoption in existing apps
201
- - 🌐 **Multi-language client generation** (TypeScript, Python, Go)
202
- - 📊 **Enhanced observability** with distributed tracing
203
- - 🔌 **Plugin ecosystem** for community extensions
181
+ - Rails integration for seamless adoption in existing apps
182
+ - More client generators (Python, Go)
183
+ - Enhanced observability and tracing
184
+ - Plugin ecosystem for community extensions
204
185
 
205
186
  ## Try It Today
206
187
 
207
188
  RapiTapir is **production-ready** with comprehensive tests, clear documentation, and real-world examples. Whether you're building a new API or enhancing an existing one, RapiTapir helps you write better Ruby code.
208
189
 
209
190
  **Links:**
210
- - 📦 **Gem**: [rubygems.org/gems/rapitapir](https://rubygems.org/gems/rapitapir)
211
- - 🏠 **Homepage**: [riccardomerolla.github.io/rapitapir](https://riccardomerolla.github.io/rapitapir)
212
- - 💻 **Source**: [github.com/riccardomerolla/rapitapir](https://github.com/riccardomerolla/rapitapir)
213
- - 📖 **Docs**: [Examples and guides](https://github.com/riccardomerolla/rapitapir/tree/main/examples)
191
+ - Gem: https://rubygems.org/gems/rapitapir
192
+ - Homepage: https://riccardomerolla.github.io/rapitapir
193
+ - Source: https://github.com/riccardomerolla/rapitapir
194
+ - Docs: https://github.com/riccardomerolla/rapitapir/tree/main/examples
214
195
 
215
196
  ---
216
197
 
@@ -0,0 +1,33 @@
1
+ # ADR-0001: Base class strategy (SinatraRapiTapir) vs manual extension
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ Historically, users registered the Sinatra extension manually and wired routes/DSL themselves. This added boilerplate and repeated setup across services, making the first-run experience slower and error-prone.
9
+
10
+ ## Decision
11
+
12
+ Adopt a first-class base class, `SinatraRapiTapir`, as the primary way to build APIs:
13
+
14
+ - Auto-registers the RapiTapir Sinatra extension.
15
+ - Exposes the enhanced HTTP verb DSL (GET/POST/...).
16
+ - Provides `development_defaults!` and `production_defaults!` helpers for sensible defaults (CORS/docs/health in dev; security headers/rate limit in prod).
17
+ - Keeps manual registration supported for power users and non-Sinatra stacks.
18
+
19
+ ## Consequences
20
+
21
+ - Pros: Minimal boilerplate, consistent defaults, faster time-to-first-endpoint, clearer docs.
22
+ - Cons: Slightly more “magic”; divergence from vanilla Sinatra learning resources.
23
+ - Mitigations: Thorough docs, explicit opt-outs, manual extension path remains supported.
24
+
25
+ ## Alternatives considered
26
+
27
+ - Only manual extension: simpler mental model but worse DX and more boilerplate.
28
+ - Separate installer generator: adds tooling complexity without runtime benefit.
29
+
30
+ ## Follow-ups
31
+
32
+ - Ensure README and examples prefer `SinatraRapiTapir` while linking manual alternative.
33
+ - Add integration tests for both base class and manual setup to avoid regressions.
@@ -0,0 +1,30 @@
1
+ # ADR-0002: Type shortcut (T) and type system boundaries
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ The library offers a rich runtime type system (primitives, composites, optionals, constraints, coercion). Frequent usage leads to verbosity (e.g., `RapiTapir::Types.string`).
9
+
10
+ ## Decision
11
+
12
+ - Provide a global, ergonomic alias `T` to the type system (e.g., `T.string`, `T.array(T.integer)`, `T.hash({ "id" => T.integer })`).
13
+ - Keep the type system strictly runtime-validating with coercion where safe; no mandatory compile-time type checker dependency.
14
+ - Maintain boundaries: core remains independent of Sorbet/RBS; optional generators/adapters may be provided later.
15
+
16
+ ## Consequences
17
+
18
+ - Pros: Concise schemas, consistent across DSL and apps, lower ceremony.
19
+ - Cons: Potential namespace collision in extreme cases.
20
+ - Mitigations: `T` is introduced in RapiTapir surface with clear docs; fallback to fully-qualified `RapiTapir::Types` always available.
21
+
22
+ ## Alternatives considered
23
+
24
+ - No shortcut: more explicit but verbose.
25
+ - Multiple shortcuts per namespace: increases confusion and conflicts.
26
+
27
+ ## Follow-ups
28
+
29
+ - Keep schema examples in docs using `T` for clarity.
30
+ - Provide guidance on custom types and how to avoid collisions.
@@ -0,0 +1,32 @@
1
+ # ADR-0003: OpenAPI source-of-truth and documentation flow
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ We generate OpenAPI from endpoint definitions. Competing approaches: maintain OpenAPI by hand and generate code from it, or treat the DSL as the single source of truth (SSOT).
9
+
10
+ ## Decision
11
+
12
+ Use the RapiTapir DSL as the SSOT. All documentation artifacts are derived from code:
13
+
14
+ - Generate OpenAPI 3.0.3 (JSON/YAML) from endpoints.
15
+ - Generate interactive HTML docs and Markdown from the same model.
16
+ - Serve docs via CLI/dev server or mount in-app.
17
+ - Avoid editing generated OpenAPI by hand; support customization via DSL metadata and documented extension points.
18
+
19
+ ## Consequences
20
+
21
+ - Pros: Docs stay in sync with code; fewer drift bugs; simpler workflow for Ruby teams.
22
+ - Cons: Some OpenAPI-first workflows may need additional annotations in code.
23
+ - Mitigations: Rich metadata helpers (summary/description/tags/examples), selective overrides where needed.
24
+
25
+ ## Alternatives considered
26
+
27
+ - OpenAPI-first: stronger language-agnostic posture, but duplicates schema logic and increases drift.
28
+
29
+ ## Follow-ups
30
+
31
+ - Add CI job to generate/validate OpenAPI for examples to prevent drift.
32
+ - Document how to inject vendor extensions and examples through DSL metadata.
@@ -0,0 +1,34 @@
1
+ # ADR-0004: Client generation target (TypeScript first) and interface conventions
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ We can generate clients in multiple languages. The highest demand from users is a typed browser/Node ecosystem client with first-class DX.
9
+
10
+ ## Decision
11
+
12
+ Prioritize TypeScript as the official first-class generated client:
13
+
14
+ - Emit strongly-typed request/response models and method signatures.
15
+ - Promise-based API with configurable baseUrl and fetch/adapter options.
16
+ - Typed error envelope for non-2xx responses (e.g., discriminated union or exception type).
17
+ - Keep the generator pluggable to allow future languages (Ruby, Python) without coupling core.
18
+
19
+ ## Consequences
20
+
21
+ - Pros: Maximizes reach for frontend/backend TS users; fast feedback loop; strong typing.
22
+ - Cons: Non-TS ecosystems need to wait for parity.
23
+ - Mitigations: Stable generator interface; community templates for other languages.
24
+
25
+ ## Conventions
26
+
27
+ - Method names derived from path + HTTP verb; idempotent naming for GET/list/show.
28
+ - Query/path/body segmentation mirrors server types.
29
+ - Semantic versioning of client generator to avoid breaking downstream apps.
30
+
31
+ ## Follow-ups
32
+
33
+ - Add examples for browser and Node usage, including auth headers and retries.
34
+ - Track demand for additional languages and prioritize accordingly.
@@ -0,0 +1,32 @@
1
+ # ADR-0005: Authentication architecture (schemes + helpers + middleware)
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ APIs require flexible authentication/authorization mechanisms. We support OAuth2/JWT, bearer/api-key/basic, and scope-based access control across different stacks.
9
+
10
+ ## Decision
11
+
12
+ Adopt a layered auth architecture:
13
+
14
+ - Schemes: `RapiTapir::Auth::Schemes::*` (Bearer, JWT, OAuth2, Basic, ApiKey) encapsulate parsing/verification and `challenge` strings.
15
+ - Middleware: Authentication (build context), Authorization (scope checks), SecurityHeaders, CORS, RateLimiting.
16
+ - Helpers: In Sinatra integration, expose `authenticate_oauth2`, `authorize_oauth2!`, `authenticated?`, `has_scope?`, and `current_auth_context`.
17
+ - Provider-agnostic: Auth0 and generic OAuth2 supported via configuration; JWKS-based JWT verification.
18
+
19
+ ## Consequences
20
+
21
+ - Pros: Clear separation, testable units, provider flexibility, easy to reason about.
22
+ - Cons: Multiple layers increase surface area.
23
+ - Mitigations: Defaults for common cases; comprehensive examples and specs.
24
+
25
+ ## Alternatives considered
26
+
27
+ - Hard-wire to a specific provider: faster initially but vendor lock-in and reduced portability.
28
+
29
+ ## Follow-ups
30
+
31
+ - Convert pending OAuth2/JWT tests to pass using deterministic JWKS fixtures.
32
+ - Document error semantics and standardize WWW-Authenticate challenges across schemes.
@@ -0,0 +1,30 @@
1
+ # ADR-0006: Observability defaults (health, logging, metrics/tracing hooks)
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ Production services benefit from consistent, low-friction observability. The library ships helpers and middleware for health, logging, metrics, and tracing, while keeping exporters optional.
9
+
10
+ ## Decision
11
+
12
+ - Development defaults enable: health endpoint, CORS, docs, basic metrics/logging.
13
+ - Production defaults focus on security headers and safe defaults; observability can be enabled via explicit configuration blocks.
14
+ - Provide hooks for Prometheus metrics and OpenTelemetry tracing; do not hard-depend on vendors.
15
+ - Health check registry supports built-in and custom checks.
16
+
17
+ ## Consequences
18
+
19
+ - Pros: Fast local experience, predictable prod posture, portable observability across vendors.
20
+ - Cons: Users may expect batteries-included exporters.
21
+ - Mitigations: Snippets and guides for wiring popular backends; small glue modules where useful.
22
+
23
+ ## Alternatives considered
24
+
25
+ - Ship tight integrations by default: increases maintenance and pulls heavy deps into core.
26
+
27
+ ## Follow-ups
28
+
29
+ - Add labeled metrics examples and OTLP wiring snippets.
30
+ - Provide a minimal benchmark/perf budget harness to monitor overhead.
@@ -0,0 +1,30 @@
1
+ # ADR-0007: AI features scope (RAG/LLM/MCP) and maintainability boundaries
2
+
3
+ Date: 2025-08-08
4
+ Status: Accepted
5
+
6
+ ## Context
7
+
8
+ RapiTapir includes AI-adjacent features: LLM instruction generation, a simple RAG pipeline (memory backend), and MCP export for agent tooling. These should remain optional and decoupled from core HTTP concerns.
9
+
10
+ ## Decision
11
+
12
+ - Namespace AI features under `RapiTapir::AI` and keep them opt-in.
13
+ - Provide provider-agnostic interfaces; avoid hard vendor locks and network calls in core.
14
+ - Ship deterministic test doubles and local-only defaults (e.g., memory backend) for reliability.
15
+ - Limit feature scope to developer tooling and augmentation (instructions, docs, context), not business logic.
16
+
17
+ ## Consequences
18
+
19
+ - Pros: Clear boundaries, low risk to core stability, easy to disable.
20
+ - Cons: Smaller immediate feature set vs vendor SDKs.
21
+ - Mitigations: Extension points for providers; examples that demonstrate integration without coupling.
22
+
23
+ ## Alternatives considered
24
+
25
+ - Deep vendor integrations in core: faster to demo, harder to maintain and test.
26
+
27
+ ## Follow-ups
28
+
29
+ - Add guidance on switching RAG backends and plugging external vector stores.
30
+ - Provide examples for MCP export consumption in popular agents.
@@ -0,0 +1,46 @@
1
+ # Architectural Decision Records (ADRs)
2
+
3
+ This directory contains Architecture Decision Records (ADRs) that document significant architectural decisions made throughout the RapiTapir project.
4
+
5
+ ## Purpose
6
+
7
+ - Maintain a clear history of architectural choices and their rationale.
8
+ - Provide context and rationale for future maintainers and contributors.
9
+
10
+ ## ADR Structure
11
+
12
+ Each ADR is a Markdown file with a sequential identifier and a descriptive title:
13
+
14
+ ```
15
+ NNNN-short-title.md
16
+ ```
17
+
18
+ Inside, ADRs follow this structure:
19
+
20
+ ```
21
+ # ADR NNNN: Short Title
22
+
23
+ Date: YYYY-MM-DD
24
+
25
+ ## Status
26
+
27
+ Proposed | Accepted | Deprecated
28
+
29
+ ## Context
30
+
31
+ Describe the context and forces leading to this decision.
32
+
33
+ ## Decision
34
+
35
+ Describe the decision and its rationale.
36
+
37
+ ## Consequences
38
+
39
+ Describe the resulting consequences, trade-offs, and impacts.
40
+ ```
41
+
42
+ ## Creating a New ADR
43
+
44
+ 1. Copy `template.md` and rename to the next sequence number, e.g., `0002-add-auth-cache.md`.
45
+ 2. Fill in date, status, context, decision, and consequences.
46
+ 3. Commit the new ADR file to the repository.
@@ -0,0 +1,24 @@
1
+ # ADR-NNNN: Title
2
+
3
+ Date: YYYY-MM-DD
4
+ Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
5
+
6
+ ## Context
7
+
8
+ Describe the background and forces leading to this decision.
9
+
10
+ ## Decision
11
+
12
+ Record the decision made, with enough detail to be unambiguous.
13
+
14
+ ## Consequences
15
+
16
+ List positive, negative, and neutral consequences. Consider security, performance, DX, and maintenance.
17
+
18
+ ## Alternatives considered
19
+
20
+ Briefly list alternatives and why they were not chosen.
21
+
22
+ ## Follow-ups
23
+
24
+ List tasks, docs, or changes required to uphold this decision.