mk_framework 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f37bb87398d93ff1849ae3df5cd7efac0632ebe204505aca673a8394a65d71c8
+  data.tar.gz: 93574025a9c4489ac0b395b968370e48679741a0aa40c229d861023209c78e60
+SHA512:
+  metadata.gz: a589434c614336c30e21ccd5f319eb08a1ab98dac0733f4c7ec243cc0beee58faa0abe654b2cec5a56b27980c73329c8bd1a70c1b0f13dd17125feaa50530047
+  data.tar.gz: 9d855021ee2a3cebb77f3160292898ad676c8dd79c169c6001651c40d74487a909280f16f6442b569f7ab5edf96433e5274de932605fda737c697c428a393765

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.2.0 — 2026-09-08
+
+- Release MK as an installable gem with standalone framework tests and packaging.
+- Move all seven sample applications, their shared support, and integration tests
+  to [mk_framework_sample_apps](https://github.com/makevoid/mk_framework_sample_apps).
+  Applications depend on `mk_framework ~> 0.2.0` from RubyGems.
+- Remove application-only development dependencies and legacy test-helper paths
+  from the framework repository.
+
+## 0.1.0 — unreleased
+
+- Package MK as an MIT-licensed gem, with a standalone test suite and Ruby 3.2–4.0 CI.
+- Compile an immutable resource tree at explicit application boot. Add deep nesting,
+  shallow routes, namespaces, custom actions, action allowlists, configurable IDs,
+  route inspection, HEAD, PATCH, PUT, DELETE, and 405/Allow responses.
+- Preserve POST update/delete URLs as configurable compatibility aliases.
+- Persist returned Sequel records by registered action before response handlers:
+  create/update save once, delete invokes destroy hooks, show/index materialize data.
+  Handlers receive raw hashes/arrays; explicit multi-record transactions remain available.
+- Add typed input allowlists, bounded pagination and request bodies, request IDs,
+  resilient JSON errors, recursive parameter redaction, and request hooks.
+- Scope and namespace the sample applications. Add migrations, test-only databases,
+  deterministic weather tests, boot checks, and relationship/persistence regressions.
+- Correct the weather entrypoint, explicitly require Excon, bound upstream timeouts,
+  atomically refresh cached locations, and label three-hour forecasts accurately.
+- Update dependencies, documentation, and the aggregate test runner.
+
+### Migration required
+
+See [the upgrade guide](docs/upgrading.md). The implicit handler persistence API and
+`register_nested_resource` have been replaced. The 0.1.0 prototype was not published; these changes first ship in 0.2.0.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Canessa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# MK Framework
+
+Small, explicit JSON APIs on [Roda](https://roda.jeremyevans.net/), with optional
+[Sequel](https://sequel.jeremyevans.net/) persistence. Ruby 3.2 or newer. MIT licensed.
+
+MK gives each action an obvious home:
+
+```text
+app.rb
+models/post.rb
+routes/posts/controllers/create.rb
+routes/posts/handlers/create.rb
+```
+
+Controllers select and prepare records. Framework dispatch persists standard action
+results and converts them to raw data. Handlers filter fields and format responses.
+Authorization, association selection, and multi-record transactions remain explicit Ruby.
+You can read the core in `lib/mk_framework/`; no ORM or database is loaded until you
+require `mk_framework/sequel`.
+
+## Install
+
+```sh
+gem install mk_framework -v 0.2.0
+```
+
+Or add it to your application's Gemfile:
+
+```ruby
+source 'https://rubygems.org'
+gem 'mk_framework', '~> 0.2.0'
+```
+
+Run `bundle install`. Add `sequel` and your database driver if you use
+`mk_framework/sequel`; both are optional application dependencies.
+
+## Try the examples
+
+The seven sample applications live in
+[mk_framework_sample_apps](https://github.com/makevoid/mk_framework_sample_apps)
+and install MK from RubyGems. Both GitHub repositories are private; installing the
+published gem does not require access to the framework repository.
+
+From a sample-app checkout:
+
+```sh
+git clone git@github.com:makevoid/mk_framework_sample_apps.git
+cd mk_framework_sample_apps/sample_app4
+bundle install
+bundle exec rake db:migrate      # Explicit schema setup; never done on server boot
+bundle exec rake routes
+bundle exec rspec
+```
+
+All sample tests force `RACK_ENV=test` and use private in-memory SQLite databases.
+They never open `DATABASE_URL` or the development SQLite files. The weather tests
+stub HTTP and require no personal API key or internet connection.
+
+| Sample | Demonstrates |
+| --- | --- |
+| [1](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app1/README.md) | Basic todos and JSON CRUD |
+| [2](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app2/README.md) | Todo validation and request specs |
+| [3](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app3/README.md) | Custom response envelopes |
+| [4](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app4/README.md) | Blog posts, nested comments, parent scoping |
+| [5](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app5/README.md) | Kanban cards, status validation, nested comments |
+| [6](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app6/README.md) | Weather client, deadlines, atomic cache refresh |
+| [7](https://github.com/makevoid/mk_framework_sample_apps/blob/main/sample_app7/README.md) | Three-column Kanban board, ordering, priorities, filters, archive and comments |
+
+## An application
+
+Define classes in your own module. Configure an absolute root, then call `boot!`
+after the class definition. Boot loads route files, resolves action classes, checks
+the route table, and freezes application configuration before serving requests.
+
+```ruby
+require 'mk_framework'
+
+module Blog
+  class App < MK::Application
+    configure root: __dir__, namespace: Blog
+
+    resource_routes do
+      resources :posts do
+        resources :comments
+      end
+    end
+  end
+
+  App.boot!
+end
+```
+
+In `config.ru`:
+
+```ruby
+require_relative 'app'
+run Blog::App.app
+```
+
+By convention, `posts/create` connects `Blog::PostsCreateController` to
+`Blog::PostsCreateHandler`. Without a `resource_routes` block, MK discovers the
+standard action files under `routes/*/controllers`; explicit declarations are
+recommended for APIs with nested or custom routes. Missing handlers fail at boot.
+
+## Controllers prepare; the framework persists; handlers respond
+
+These action files assume your application has explicitly required its `Post`
+model, backed by a migrated Sequel dataset, before calling `boot!`.
+
+```ruby
+require 'mk_framework/sequel'
+
+module Blog
+  class PostsCreateController < MK::Controller
+    route do |r|
+      Post.new(r.input.permit(title: String, description: [String, NilClass]))
+    end
+  end
+
+  class PostsCreateHandler < MK::Handler
+    handler do |r|
+      r.response.status = 201
+      {post: fields(model, :id, :title, :description)}
+    end
+  end
+end
+```
+
+Requiring `mk_framework/sequel` enables this lifecycle for a controller's returned
+Sequel model, using the registered route action:
+
+| Action | Before the handler |
+| --- | --- |
+| create | `save`, then `values` |
+| update | `save`, then `values` |
+| delete | `destroy` with hooks, then `values` |
+| show | `values` |
+| index | Materialize the collection and convert records to `values` |
+
+Create controllers return `Post.new(...)`; updates find a record and call `set(...)`;
+deletes return the record to delete. Do not save or destroy these results manually.
+PATCH/PUT and POST compatibility aliases share the same lifecycle. Custom action
+names do not automatically write, regardless of their controller class name.
+Validation failures return 422; expected constraint/hook conflicts return 409;
+unexpected database failures reach the sanitized 500 handler.
+
+Records and datasets nested in hashes/arrays are recursively converted to raw data,
+without recursively saving or deleting them. Controllers explicitly select any
+associations to include; conversion does not load associations implicitly. Handlers
+receive hashes and arrays, filter them with `fields` or `slice` and a model's
+`public_attributes_list`, and never query the database.
+
+Plain hash/array results remain usable for service-backed actions. For related
+writes, use `DB.transaction` and explicit saves (or `MK::Persistence` helpers), then
+return raw data so the framework does not save a completed write again.
+
+Handlers return a Hash or Array, or use
+`r.halt` for an explicit response such as 204. Returning `nil` from a controller
+means the resource was not found.
+Inside action blocks, use `next` for an early result; Ruby's `return` would try to
+return from the context where the block was originally defined.
+
+## Routes and HTTP
+
+For `resources :posts`, MK registers:
+
+| Method | Path | Action |
+| --- | --- | --- |
+| GET / HEAD | `/posts` | index |
+| POST | `/posts` | create |
+| GET / HEAD | `/posts/:id` | show |
+| PATCH / PUT | `/posts/:id` | update |
+| DELETE | `/posts/:id` | delete |
+
+PUT and PATCH reach the same action; the sample controllers update only supplied
+fields. Define a separate custom action if your API needs strict replacement
+semantics. The old `POST /posts/:id` and `POST /posts/:id/delete` routes remain
+enabled by default. Disable them with `configure legacy_post_routes: false`.
+Known paths with unsupported methods return 405 and `Allow`; unknown paths return
+404. CORS preflights are application policy, not automatically enabled.
+
+Read [nested routes and authorization](docs/routing.md) for scopes, namespaces,
+shallow routes, custom actions, explicit class mappings, and parent ownership.
+
+## Inputs, responses, and errors
+
+- `r.path_params` is a frozen symbol-keyed hash containing only URL captures.
+- `r.input` validates body/query input independently of path IDs. `require(:name)`
+  requires a typed field; `permit(name: String)` allows only declared fields.
+- `:boolean` accepts booleans and the form strings `true`, `false`, `1`, `0`.
+  Nullable fields must explicitly include `NilClass` in their accepted types.
+- `r.params` remains compatible with older controllers, with path IDs taking
+  precedence. Never use client input to establish a parent relationship.
+- `r.page` validates `limit` (default 25, maximum 100) and `offset` (maximum 10,000).
+  `paginate(dataset, r)` in `MK::Persistence` uses an ordered, bounded query.
+  Implement cursor pagination in your application when large offsets are needed.
+- JSON request bodies must be objects. Malformed JSON and malformed query inputs
+  produce 400. Bodies above 1 MiB produce 413, including bodies without a length.
+- `MK::BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `Conflict`,
+  `ValidationError`, and `BadGateway` represent intentional public errors.
+  Their messages are public: never place secrets in them.
+- Unexpected errors return JSON with `error: "Server error"` and a request ID.
+  The same ID appears in `X-Request-ID` and the structured error log.
+
+Production is the safe default. Set `RACK_ENV=development` explicitly for debug
+details. Configure a logger using `configure logger: Logger.new($stdout)`, or
+`setup_logger(io)`. `configure filter_parameters: %w[ssn]` adds fields to the
+built-in recursive redaction list. Production logs omit raw exception messages
+because database and network exceptions can contain credentials or SQL values.
+
+## Release and deployment
+
+```sh
+bundle exec rake
+bundle exec rake build
+```
+
+The gem is written to `pkg/mk_framework-0.2.0.gem`. See
+[deployment](docs/deployment.md) for migrations, connections, authentication,
+timeouts, logging, and release verification, and [upgrading](docs/upgrading.md)
+for changes from the prototype. CI covers Ruby 3.2, 3.3, 3.4, and 4.0 on Linux.
+
+Applications can optionally `require 'mk_framework/testing'` and include
+`MK::Framework::Spec` in RSpec to use Rack::Test and the `resp` JSON helper.
+Install `rack-test` separately in the application's test bundle.

data/docs/deployment.md

@@ -0,0 +1,115 @@
+# Deployment and release
+
+MK supplies routing, explicit action dispatch, JSON errors, and request boundaries.
+Authentication policies, schema design, external services, and process operation
+belong to the application. The APIs in the separate
+[example repository](https://github.com/makevoid/mk_framework_sample_apps) are
+demonstrations without authentication.
+
+## Configuration
+
+Set `RACK_ENV=production` explicitly in deployments; it is also MK's default when
+the variable is absent. Debug details are enabled only for `development`.
+
+Configure the app before `boot!`:
+
+```ruby
+configure root: __dir__, namespace: MyApp,
+          logger: Logger.new($stdout),
+          filter_parameters: %w[ssn access_code],
+          max_body_bytes: 1_048_576,
+          page_size: 25, max_page_size: 100, max_offset: 10_000
+```
+
+Boot eagerly loads route files and freezes route/configuration state before
+requests. Restart after code changes. Controller and handler instances are created
+per request. Avoid mutable class variables for request data; use local variables,
+instance variables, or the Rack request environment.
+
+## Database lifecycle
+
+The samples accept `DATABASE_URL`, `DB_POOL_SIZE` (default 5), and
+`DB_POOL_TIMEOUT` (default 5 seconds). Without a URL they use a SQLite file under
+the sample directory, independent of the current working directory. Tests always
+use private in-memory databases, regardless of these environment variables.
+
+Run migrations once as a release step before starting workers. Keep backups and
+test restore procedures. Do not put schema changes in app boot or request code.
+Sample migrations use Sequel's migration version table and fail on an unexpected
+pre-existing schema; the upgrade guide covers prototype databases.
+
+For another adapter, install its driver explicitly and test the migrations and
+queries against that adapter. The local automated suite exercises SQLite; it does
+not certify PostgreSQL/MySQL behavior. Size the pool for the server's request
+threads and the total number of worker processes within the database connection
+budget. Use explicit transactions for related writes and retain database-level
+foreign keys, uniqueness constraints, and indexes.
+
+When preloading and forking a server, disconnect Sequel connections before fork
+so child processes do not inherit live connections. Sequel reconnects on demand.
+Apply this to every database owned by your app. The samples expose their database
+as `SampleAppN::DB`. Test the specific Puma worker configuration you deploy;
+Rack entrypoint specs do not exercise process forking.
+
+The sample models update timestamps through Sequel's timestamps plugin. SQL writes
+outside those models must set timestamps themselves. Do not use unbounded `.all`
+queries in endpoints; use `paginate` or application-specific cursor pagination.
+
+## Authentication, browser clients, and limits
+
+Use Rack/Roda authentication middleware or `before_request` to validate credentials
+and establish a trusted principal. Apply authorization in controllers to both
+resource ownership and the requested action. Never trust a query/body tenant ID.
+See the routing guide and `spec/ownership_spec.rb` for an executable scoping test.
+
+For session/cookie authentication, add CSRF protection and appropriate secure,
+HTTP-only, same-site cookie settings using the corresponding Roda plugins.
+For cross-origin clients, explicitly allow trusted origins, headers, and methods
+through your chosen CORS middleware. MK does not enable permissive CORS or infer
+authorization from URL nesting.
+
+Terminate TLS at the server or a trusted proxy. Configure trusted host/proxy
+handling for your deployment, especially before generating absolute URLs or
+trusting forwarded client addresses. Set proxy/server header and request timeouts,
+connection limits, and rate limits. MK's body cap bounds buffered request memory;
+it is not a timeout or a rate limiter. File streaming APIs should use a separately
+configured/mounted application with an appropriate body policy.
+
+External HTTP clients need connect/read/write deadlines. The weather example uses
+3/5/5 seconds and atomic cache upserts. Its cache does not implement distributed
+request coalescing: simultaneous misses can make redundant upstream requests, but
+cannot create duplicate location rows. Add quotas/coalescing where upstream costs
+or traffic justify it.
+
+## Logs and observability
+
+Each request gets a server-generated `X-Request-ID`. Unexpected failures write a
+structured JSON event through the configured logger, with the same identifier,
+error class, stack, and recursively filtered already-parsed parameters. Production
+logs omit raw exception messages and model values. A failed log sink does not
+replace the error response. Add domain-specific sensitive keys to the filter.
+
+Intentional public errors are not logged as unexpected failures. Collect access
+logs, latency, request counts, status counts, database pool pressure, and readiness
+checks with your server/middleware/monitoring stack. Apply redaction to those logs
+too: external middleware is not covered by MK's parameter filter. Log retention
+and access permissions are deployment decisions.
+
+## Release procedure
+
+1. Run `bundle install` and `bundle exec rake` with frozen lockfiles in CI.
+2. Require the Linux Ruby matrix to pass before publishing. Local results on one
+   Ruby version are not a substitute for that matrix.
+3. Run `bundle exec rake build`. Inspect and install the generated gem in a clean
+   environment, including `require 'mk_framework'` without Sequel and the optional
+   `require 'mk_framework/sequel'` with its dependency installed.
+4. Test the production app entrypoint against a newly migrated test database and
+   your intended server/proxy configuration. Test existing-data upgrades separately.
+5. Update the version/changelog and publish the reviewed gem using an authorized
+   RubyGems account. The gem metadata requires MFA. No publish task runs automatically.
+
+CI runs framework/request tests and builds the gem on Ruby 3.2, 3.3, 3.4, and 4.0.
+The framework root `rake` command runs its standalone specs. The separate sample
+repository runs its integration tests and all seven application suites against the
+published gem, isolating Bundler Gemfile and lockfile paths for each child and
+propagating failures.

data/docs/routing.md

@@ -0,0 +1,160 @@
+# Resource routing
+
+## Deep resources
+
+This declaration belongs in an application's `resource_routes` block. Parent
+resources can use `only: []` when they exist only to scope child endpoints.
+
+```ruby
+scope '/api/v1' do
+  resources :organizations, only: [] do
+    resources :projects, only: [] do
+      resources :comments
+    end
+  end
+end
+```
+
+`PATCH /api/v1/organizations/one/projects/two/comments/three` dispatches to
+`CommentsUpdateController` and `CommentsUpdateHandler` in the configured module.
+The frozen path parameters are:
+
+```ruby
+{organization_id: 'one', project_id: 'two', id: 'three'}
+```
+
+Nested collection routes contain ancestor IDs but no leaf `id`. Arbitrary string
+identifiers, including UUIDs and slugs, are supported; applications validate their
+identifier formats. Query and JSON input cannot replace these captures.
+
+The declarations describe URLs. Action files remain under `routes/comments/`.
+Routing does not infer database associations or load parents automatically.
+
+## Authentication and ownership
+
+Use `before_request` for authentication shared by generated and native Roda routes:
+
+```ruby
+before_request do |r|
+  # authenticate must verify the token/session and return a trusted user object.
+  r.env['current_user'] = authenticate(r) or raise MK::Unauthorized
+end
+```
+
+Load children through an authorized dataset in the controller:
+
+```ruby
+user = r.env.fetch('current_user')
+organization = user.organizations_dataset
+  .where(id: r.path_params.fetch(:organization_id)).first or raise MK::NotFound
+project = organization.projects_dataset
+  .where(id: r.path_params.fetch(:project_id)).first or raise MK::NotFound
+comment = project.comments_dataset
+  .where(id: r.path_params.fetch(:id)).first or raise MK::NotFound
+```
+
+Use that scoped lookup for reads, updates, and deletes. For creates, assign the
+foreign key from the authorized parent, not from `r.input`. Database foreign keys
+remain necessary to protect against concurrent deletion of a parent. Resource
+ownership is separate from whether the user is allowed to perform an action;
+enforce both. The blog and Kanban samples are public demonstrations, not account
+systems. `spec/ownership_spec.rb` exercises authenticated three-level scoping.
+
+## Shallow routes
+
+```ruby
+scope '/api/v1' do
+  resources :posts do
+    resources :comments, shallow: true
+  end
+end
+```
+
+Collections use `/api/v1/posts/:post_id/comments`; members use
+`/api/v1/comments/:id`. There is no top-level comment collection and no nested
+member route in this mode. Shallow members must still be loaded through the
+authenticated user's authorized dataset. The shorter URL is not permission.
+
+## Names, scopes, and actions
+
+`scope '/api/v1'` changes the URL only. `namespace :admin` changes both the URL
+prefix and the Ruby namespace (for example `Blog::Admin`). That module must exist
+before route compilation. Use `namespace: SomeModule` on a resource to override
+its action namespace without changing the URL.
+
+```ruby
+resources :people, singular: :person, parent_key: :owner_id do
+  resources :user_profiles, param: :slug, only: %i[index show]
+end
+```
+
+`param` names a member's own identifier. `parent_key` names the capture passed to
+descendants. `singular` controls the default parent key and missing-resource label.
+Basic inflection covers underscores, `companies`, and common irregular nouns;
+set `singular` explicitly for domain terms. Repeated resources in one hierarchy
+need distinct parent keys; duplicate parameter names fail at boot.
+
+Custom actions can use any controller result, including service results without
+a Sequel model:
+
+```ruby
+resources :posts do
+  member :publish, via: :post
+  collection :search, via: :get
+end
+```
+
+This connects `PostsPublishController`/`PostsPublishHandler` to
+`POST /posts/:id/publish`, and `PostsSearchController`/`PostsSearchHandler` to
+`GET /posts/search`. Literal routes take precedence over identifier captures.
+
+Pass `controller:` and `handler:` classes to custom actions, or override standard
+actions with explicit class pairs:
+
+```ruby
+resources :posts, only: [:show], actions: {
+  show: [PublicPostController, PublicPostHandler]
+}
+```
+
+The full default action list is `index`, `show`, `create`, `update`, `delete`.
+Missing actions, missing blocks, and duplicate method/path combinations fail at
+boot. `App.route_table` prints the resolved paths and classes.
+
+## Native Roda routes
+
+An ordinary `route` block runs before generated routes. A matching Roda branch
+or a non-nil return value completes the request; nil falls through to resources.
+
+```ruby
+route do |r|
+  r.get('health') { {ok: true} }
+  r.on('metrics') { r.run(metrics_app) }
+end
+```
+
+Define routes, middleware, configuration, and hooks before `boot!`. The application
+is frozen afterward; development changes require a process restart.
+An unbooted shared application base can be subclassed: configuration, resource
+declarations, and request hooks are inherited. Boot concrete applications only;
+Roda does not allow subclassing an already frozen application.
+
+## Nested writes
+
+Nested URLs do not imply automatic nested assignment. Validate the payload and
+allowlist each object's fields explicitly, then use one transaction:
+
+```ruby
+DB.transaction do
+  project = persist(Project.new(project_attributes))
+  validated_comment_attributes.each do |attributes|
+    persist(Comment.new(attributes.merge(project_id: project.id)))
+  end
+  project.values # Already saved: return raw data to skip automatic action persistence.
+end
+```
+
+Authorize the parent before entering the transaction, bound the number of children,
+and validate each child payload. Let validation exceptions escape the transaction
+so it rolls back. External API calls are not rolled back with database writes;
+perform them outside a database transaction or use an application-owned outbox.