rapitapir 0.1.2 → 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 (161) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +7 -7
  3. data/.rubocop_todo.yml +88 -0
  4. data/CHANGELOG.md +29 -1
  5. data/README.md +1339 -236
  6. data/RUBY_WEEKLY_LAUNCH_POST.md +200 -0
  7. data/docs/RAILS_INTEGRATION_IMPLEMENTATION.md +209 -0
  8. data/docs/SINATRA_EXTENSION.md +399 -348
  9. data/docs/STRICT_VALIDATION.md +229 -0
  10. data/docs/VALIDATION_IMPROVEMENTS.md +218 -0
  11. data/docs/adr/0001-base-class-strategy.md +33 -0
  12. data/docs/adr/0002-type-shortcut-and-type-system.md +30 -0
  13. data/docs/adr/0003-openapi-source-of-truth.md +32 -0
  14. data/docs/adr/0004-client-generation-typescript-first.md +34 -0
  15. data/docs/adr/0005-auth-architecture.md +32 -0
  16. data/docs/adr/0006-observability-defaults.md +30 -0
  17. data/docs/adr/0007-ai-scope-and-boundaries.md +30 -0
  18. data/docs/adr/README.md +46 -0
  19. data/docs/adr/template.md +24 -0
  20. data/docs/ai-integration-plan.md +112 -0
  21. data/docs/auto-derivation.md +505 -92
  22. data/docs/blueprint.md +92 -4
  23. data/docs/endpoint-definition.md +536 -129
  24. data/docs/implementation-status.md +1 -1
  25. data/docs/n8n-integration.md +212 -0
  26. data/docs/observability.md +810 -500
  27. data/docs/using-mcp.md +93 -0
  28. data/examples/ai/knowledge_base_rag.rb +83 -0
  29. data/examples/ai/user_management_mcp.rb +92 -0
  30. data/examples/ai/user_validation_llm.rb +187 -0
  31. data/examples/auto_derivation_ruby_friendly.rb +44 -113
  32. data/examples/cli/user_api_endpoints.rb +63 -36
  33. data/examples/demo_api.rb +57 -18
  34. data/examples/enterprise_extension_demo.rb +13 -13
  35. data/examples/enterprise_rapitapir_api.rb +81 -93
  36. data/examples/nocodb/nocodb_scaffold/Gemfile +22 -0
  37. data/examples/nocodb/nocodb_scaffold/README.md +10 -0
  38. data/examples/nocodb/nocodb_scaffold/Rakefile +7 -0
  39. data/examples/nocodb/nocodb_scaffold/app/api/app.rb +1139 -0
  40. data/examples/nocodb/nocodb_scaffold/app/models/email_template.rb +6 -0
  41. data/examples/nocodb/nocodb_scaffold/app/models/faq.rb +6 -0
  42. data/examples/nocodb/nocodb_scaffold/app/models/feature.rb +6 -0
  43. data/examples/nocodb/nocodb_scaffold/app/models/idea.rb +6 -0
  44. data/examples/nocodb/nocodb_scaffold/app/models/itinerary_day.rb +6 -0
  45. data/examples/nocodb/nocodb_scaffold/app/models/route.rb +6 -0
  46. data/examples/nocodb/nocodb_scaffold/app/models/subscriber.rb +6 -0
  47. data/examples/nocodb/nocodb_scaffold/app/models/tour.rb +6 -0
  48. data/examples/nocodb/nocodb_scaffold/app/models/webhook.rb +6 -0
  49. data/examples/nocodb/nocodb_scaffold/app/models_loader.rb +3 -0
  50. data/examples/nocodb/nocodb_scaffold/config/database.yml +11 -0
  51. data/examples/nocodb/nocodb_scaffold/config.ru +9 -0
  52. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152012_create_features.rb +10 -0
  53. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152013_create_tours.rb +10 -0
  54. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152014_create_routes.rb +10 -0
  55. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152015_create_itinerary_days.rb +10 -0
  56. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152016_create_subscribers.rb +10 -0
  57. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152017_create_email_templates.rb +10 -0
  58. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152018_create_faqs.rb +10 -0
  59. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152019_create_webhooks.rb +10 -0
  60. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152020_create_ideas.rb +10 -0
  61. data/examples/nocodb/swagger.json +4378 -0
  62. data/examples/production_ready_example.rb +78 -58
  63. data/examples/rails/RAILS_8_GUIDE.md +165 -0
  64. data/examples/rails/RAILS_LOADING_FIX.rb +35 -0
  65. data/examples/rails/README.md +497 -0
  66. data/examples/rails/comprehensive_test.rb +91 -0
  67. data/examples/rails/config/routes.rb +48 -0
  68. data/examples/rails/debug_controller.rb +63 -0
  69. data/examples/rails/detailed_test.rb +46 -0
  70. data/examples/rails/enhanced_users_controller.rb +278 -0
  71. data/examples/rails/final_server_test.rb +50 -0
  72. data/examples/rails/hello_world_app.rb +116 -0
  73. data/examples/rails/hello_world_controller.rb +186 -0
  74. data/examples/rails/hello_world_routes.rb +28 -0
  75. data/examples/rails/rails8_minimal_demo.rb +132 -0
  76. data/examples/rails/rails8_simple_demo.rb +140 -0
  77. data/examples/rails/rails8_working_demo.rb +255 -0
  78. data/examples/rails/real_world_blog_api.rb +510 -0
  79. data/examples/rails/server_test.rb +46 -0
  80. data/examples/rails/test_direct_processing.rb +41 -0
  81. data/examples/rails/test_hello_world.rb +80 -0
  82. data/examples/rails/test_rails_integration.rb +54 -0
  83. data/examples/rails/traditional_app/Gemfile +37 -0
  84. data/examples/rails/traditional_app/README.md +265 -0
  85. data/examples/rails/traditional_app/app/controllers/api/v1/posts_controller.rb +254 -0
  86. data/examples/rails/traditional_app/app/controllers/api/v1/users_controller.rb +220 -0
  87. data/examples/rails/traditional_app/app/controllers/application_controller.rb +86 -0
  88. data/examples/rails/traditional_app/app/controllers/application_controller_simplified.rb +87 -0
  89. data/examples/rails/traditional_app/app/controllers/documentation_controller.rb +149 -0
  90. data/examples/rails/traditional_app/app/controllers/health_controller.rb +42 -0
  91. data/examples/rails/traditional_app/config/routes.rb +25 -0
  92. data/examples/rails/traditional_app/config/routes_best_practice.rb +25 -0
  93. data/examples/rails/traditional_app/config/routes_simplified.rb +36 -0
  94. data/examples/rails/traditional_app_runnable.rb +406 -0
  95. data/examples/rails/users_controller.rb +4 -1
  96. data/examples/serverless/Gemfile +43 -0
  97. data/examples/serverless/QUICKSTART.md +331 -0
  98. data/examples/serverless/README.md +520 -0
  99. data/examples/serverless/aws_lambda_example.rb +307 -0
  100. data/examples/serverless/aws_sam_template.yaml +215 -0
  101. data/examples/serverless/azure_functions_example.rb +407 -0
  102. data/examples/serverless/deploy.rb +204 -0
  103. data/examples/serverless/gcp_cloud_functions_example.rb +367 -0
  104. data/examples/serverless/gcp_function.yaml +23 -0
  105. data/examples/serverless/host.json +24 -0
  106. data/examples/serverless/package.json +32 -0
  107. data/examples/serverless/spec/aws_lambda_spec.rb +196 -0
  108. data/examples/serverless/spec/spec_helper.rb +89 -0
  109. data/examples/serverless/vercel.json +31 -0
  110. data/examples/serverless/vercel_example.rb +404 -0
  111. data/examples/simple_demo_api.rb +40 -7
  112. data/examples/strict_validation_examples.rb +104 -0
  113. data/examples/user_api.rb +130 -132
  114. data/examples/validation_error_examples.rb +173 -0
  115. data/lib/rapitapir/ai/llm_instruction.rb +456 -0
  116. data/lib/rapitapir/ai/mcp.rb +134 -0
  117. data/lib/rapitapir/ai/rag.rb +287 -0
  118. data/lib/rapitapir/ai/rag_middleware.rb +147 -0
  119. data/lib/rapitapir/auth/oauth2.rb +44 -58
  120. data/lib/rapitapir/cli/command.rb +392 -6
  121. data/lib/rapitapir/cli/mcp_export.rb +18 -0
  122. data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
  123. data/lib/rapitapir/cli/validator.rb +3 -7
  124. data/lib/rapitapir/core/endpoint.rb +59 -6
  125. data/lib/rapitapir/core/enhanced_endpoint.rb +3 -7
  126. data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
  127. data/lib/rapitapir/dsl/fluent_endpoint_builder.rb +53 -0
  128. data/lib/rapitapir/endpoint_registry.rb +47 -0
  129. data/lib/rapitapir/observability/health_check.rb +4 -4
  130. data/lib/rapitapir/observability/logging.rb +10 -10
  131. data/lib/rapitapir/openapi/schema_generator.rb +46 -2
  132. data/lib/rapitapir/schema.rb +2 -2
  133. data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
  134. data/lib/rapitapir/server/middleware.rb +2 -2
  135. data/lib/rapitapir/server/rack_adapter.rb +1 -3
  136. data/lib/rapitapir/server/rails/configuration.rb +77 -0
  137. data/lib/rapitapir/server/rails/controller_base.rb +185 -0
  138. data/lib/rapitapir/server/rails/documentation_helpers.rb +76 -0
  139. data/lib/rapitapir/server/rails/resource_builder.rb +181 -0
  140. data/lib/rapitapir/server/rails/routes.rb +114 -0
  141. data/lib/rapitapir/server/rails_adapter.rb +10 -3
  142. data/lib/rapitapir/server/rails_adapter_class.rb +1 -3
  143. data/lib/rapitapir/server/rails_controller.rb +1 -3
  144. data/lib/rapitapir/server/rails_integration.rb +67 -0
  145. data/lib/rapitapir/server/rails_response_handler.rb +16 -3
  146. data/lib/rapitapir/server/sinatra_adapter.rb +29 -5
  147. data/lib/rapitapir/server/sinatra_integration.rb +4 -4
  148. data/lib/rapitapir/sinatra/extension.rb +2 -2
  149. data/lib/rapitapir/sinatra/oauth2_helpers.rb +34 -40
  150. data/lib/rapitapir/types/array.rb +4 -0
  151. data/lib/rapitapir/types/auto_derivation.rb +4 -20
  152. data/lib/rapitapir/types/datetime.rb +1 -3
  153. data/lib/rapitapir/types/float.rb +2 -6
  154. data/lib/rapitapir/types/hash.rb +40 -2
  155. data/lib/rapitapir/types/integer.rb +4 -12
  156. data/lib/rapitapir/types/object.rb +6 -2
  157. data/lib/rapitapir/types.rb +6 -2
  158. data/lib/rapitapir/version.rb +1 -1
  159. data/lib/rapitapir.rb +5 -3
  160. data/rapitapir.gemspec +3 -2
  161. metadata +142 -8
data/docs/blueprint.md CHANGED
@@ -1,6 +1,94 @@
1
- # Ruby Tapir - Type-Safe HTTP API Library
2
-
3
- A Ruby library for describing, serving, consuming, and documenting HTTP APIs with type safety and developer experience in mind.
1
+ # RapiTapir (formerly "Ruby Tapir") – Type-Safe HTTP API Library
2
+
3
+ A Ruby library for describing, serving, consuming, and documenting HTTP APIs with type safety and great developer experience.
4
+
5
+ ## Status update — August 2025
6
+
7
+ This document started as an early blueprint. The project has since shipped a substantial v2.0 with many areas exceeding the original scope. Below is a concise snapshot of where we are and what we should tackle next.
8
+
9
+ ### What’s implemented and usable today
10
+
11
+ - Core DSL and Types
12
+ - Fluent HTTP verb DSL (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH)
13
+ - Global T shortcut (e.g., T.string) and rich type system with validation/coercion
14
+ - Resource builder (CRUD), error responses, metadata (summary, description, tags)
15
+ - Servers and runtime
16
+ - Rack adapter and Sinatra base class (SinatraRapiTapir) with zero-boilerplate startup
17
+ - Middleware: CORS, Security headers, Rate limiting, Request logging, Exception handler
18
+ - Health checks and observability hooks (metrics, logging, tracing scaffolding)
19
+ - Tooling and docs
20
+ - OpenAPI 3.0.3 generator (JSON/YAML) + interactive HTML docs + Markdown docs
21
+ - TypeScript client generator with types and request/response modeling
22
+ - CLI: generate openapi/docs/client, validate, serve
23
+ - Authentication
24
+ - OAuth2/JWT schemes, bearer/api-key/basic auth, scope-based authorization helpers
25
+ - AI features (distinctive)
26
+ - RAG pipeline (memory backend), LLM instruction generator, MCP exporter
27
+ - Serverless examples (new)
28
+ - Examples for AWS Lambda, Google Cloud Functions, Azure Functions, and Vercel
29
+
30
+ ### Quality gates snapshot
31
+
32
+ - Tests: 643 passing, 55 pending (primarily OAuth2 integration/helpers due to test infra)
33
+ - Coverage: ~67.6% line coverage, ~39.3% branch coverage
34
+ - Build: rspec green locally; CLI flows validated via specs
35
+
36
+ ### Notable gaps and risks
37
+
38
+ 1. Multipart/form-data & file uploads
39
+ - Missing first-class multipart parsing, file validations (size, type), and streaming
40
+ 2. Streaming/SSE/WebSockets
41
+ - No streaming response primitives, SSE helpers, or WebSocket integration
42
+ 3. Rails integration depth
43
+ - Foundational modules and route helpers exist; needs deeper, ergonomic controller wiring
44
+ 4. OAuth2 test infrastructure
45
+ - 55 pending specs rely on external JWT/JWKS/WebMock setup; needs deterministic fixtures
46
+ 5. Request body naming consistency
47
+ - Handlers typically receive JSON under `:body`; align docs/tests (deprecate `:data` alias)
48
+ 6. Documentation drift
49
+ - Some README snippets are truncated or schematic; ensure copy-paste runnable examples
50
+ 7. Performance and budgets
51
+ - No standardized benchmark suite or perf budgets in CI; schema caching hot paths can improve
52
+ 8. API stability and versioning
53
+ - Clarify SemVer guarantees, deprecations policy, and extension points
54
+ 9. Error model consistency
55
+ - Consider standard Problem Details (RFC 7807) responses and uniform error envelopes
56
+
57
+ ### Prioritized improvements (next 4–8 weeks)
58
+
59
+ - P0 – Test & DX hardening (1–2 weeks)
60
+ - Convert OAuth2/JWT specs from pending to passing using local JWKS fixtures/mocks
61
+ - Normalize request body to `inputs[:body]` in docs/tests; add deprecation notice for `:data`
62
+ - Fix/validate README code blocks; add a doc-examples smoke test in CI
63
+ - Raise coverage to ≥75% by adding failure-path tests for DSL, middleware, and generators
64
+
65
+ - P1 – Multipart/form-data + content negotiation (2–3 weeks)
66
+ - Add `multipart_body`, `file_part`, `form_field`, content-type validation, and max-size limits
67
+ - Stream uploads to tempfiles; pluggable validators for MIME/type magic
68
+
69
+ - P2 – Rails deep integration (2–3 weeks)
70
+ - Controller macro to mount endpoints with automatic validation/serialization
71
+ - Error mapping to Rails responders; parameter extraction; generators/scaffolds
72
+
73
+ - P3 – Streaming primitives (3–4 weeks)
74
+ - SSE helper (`.out(stream_body(...))`), chunked responses; foundational WebSocket adapter design
75
+
76
+ - P3 – Performance/observability (parallel, 1–2 weeks)
77
+ - Add microbench suite (endpoint build, request path, serialization); cache compiled schemas
78
+ - Optional OTLP tracing exporter wiring helper and labeled Prometheus metrics out-of-the-box
79
+
80
+ ### ADRs and decision tracking
81
+
82
+ - A new `docs/adr/` directory is in place. Suggested initial ADRs:
83
+ - [ADR-0001: Base class strategy (SinatraRapiTapir) vs manual extension](adr/0001-base-class-strategy.md)
84
+ - [ADR-0002: Type shortcut (T) and type system boundaries](adr/0002-type-shortcut-and-type-system.md)
85
+ - [ADR-0003: OpenAPI source-of-truth and doc generation flow](adr/0003-openapi-source-of-truth.md)
86
+ - [ADR-0004: Client generation target (TypeScript first) and interface conventions](adr/0004-client-generation-typescript-first.md)
87
+ - [ADR-0005: Authentication architecture (schemes + helpers + middleware)](adr/0005-auth-architecture.md)
88
+ - [ADR-0006: Observability defaults (health, logging, metrics/tracing hooks)](adr/0006-observability-defaults.md)
89
+ - [ADR-0007: AI features scope (RAG/LLM/MCP) and maintainability boundaries](adr/0007-ai-scope-and-boundaries.md)
90
+
91
+ The remainder of this document preserves the original blueprint for historical context and broader roadmap.
4
92
 
5
93
  ## Repository Structure
6
94
 
@@ -414,7 +502,7 @@ Tapir::Docs::SwaggerUI.mount(openapi_spec, path: "/docs")
414
502
  ### Technical Metrics
415
503
  - **Performance**: < 1ms overhead for simple endpoints
416
504
  - **Memory**: < 10MB memory overhead for typical applications
417
- - **Compatibility**: Support for Ruby 3.1+ and all major frameworks
505
+ - **Compatibility**: Support for Ruby 3.3+ and all major frameworks
418
506
  - **Coverage**: > 95% test coverage across all components
419
507
 
420
508
  ### Developer Experience Metrics