archipelago-rails 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f916ab9e567301591e63ef33c6c2862e7fd545f27821d37d079c348fdf31489
-  data.tar.gz: e1a648f35bdd36fee3c0c798989a613663a1bfd7c336757bd73005c60417f10a
+  metadata.gz: cc3ff097bdcb50e59b6ace832f59db53b77d1bf2d4d50e10da0595b38804afbd
+  data.tar.gz: cd849b78be869b5626e4582ddd8966be6626bce1540dcb7cb2b1613ebf238d03
 SHA512:
-  metadata.gz: ca210e1dd474885e9b322881e23ecc264ee038914de111080883e2198dd1a0dfe9f85eb6416ba72b7c6db9700fa61419003f94d6736043192c391ea2c1924317
-  data.tar.gz: 846fdc9686466a6ad5ca9a98b74ae5ca3ba9286878f5cedbc9b0410a739988558be826d10b2d49282835e6a675e010757263d4051fb35970924937db47689e5a
+  metadata.gz: 92f4432fa77ce8ee1442c210a29dbee01c22e6dac9958c7f1652290a1d9e5cde97eff943276e9d755beeff6c601958370d4a6c4c4a601fad1399a133c91df437
+  data.tar.gz: 12efedc0b57f6d59fc3a3edca4e08f51c93f3fb07a727f606939c2cca39cdc3106558ceb0a2cc11c5728f38f4f2325d431eb7635e0f338e6f566eba304f5cfe3

data/README.md

@@ -1,87 +1,339 @@
 # archipelago-rails
 
-Rails engine for Archipelago server-driven React islands.
+Rails engine for Archipelago — server-driven React islands with Inertia-style props, form handling, and real-time updates via ActionCable.
 
-## Supported Rails versions
+## Install
+
+Add to your Gemfile:
 
-- Rails `>= 7.1`
+```ruby
+gem "archipelago-rails"
+```
 
-## Development setup
+Then run the install generator:
 
 ```bash
-bundle install
+rails g archipelago:install
 ```
 
-## Run tests
+### React setup (esbuild)
 
 ```bash
-# full suite (core + rails integration tests)
-bin/test
-
-# split tasks
-bundle exec rake test:core
-bundle exec rake test:rails
+rails g archipelago:install:react
 ```
 
-## Rails version matrix (Appraisal)
+This scaffolds frontend bootstrap wiring. Options:
 
 ```bash
-bundle exec appraisal install
-bin/test-appraisal rails-7-1
-bin/test-appraisal rails-7-2
-bin/test-appraisal rails-8-1
+rails g archipelago:install:react --interactive=false --bundler=esbuild --typescript=true
+rails g archipelago:install:react --lazy_registry   # dynamic imports instead of eager
+rails g archipelago:install:react --install          # install npm packages immediately
 ```
 
-## Notes
+## Core Concepts
 
-- Controller/generator tests run against an in-test Rails application harness.
-- JS packages are tested from repository root via `yarn test`.
+Archipelago lets you embed interactive React components ("islands") inside server-rendered Rails views. Each island receives **props from the server** and can call **server-side actions** that return updated props, errors, or redirects.
 
-## Host app setup (React + esbuild)
+```
+┌─────────────────────────────────────┐
+│  Rails View                         │
+│  ┌───────────────────┐              │
+│  │  React Island     │ ← props      │
+│  │  (TeamMembers)    │              │
+│  │  ┌─────────────┐  │              │
+│  │  │ Add Member  │──┼─→ Action     │
+│  │  │ Form        │  │   (server)   │
+│  │  └─────────────┘  │              │
+│  └───────────────────┘              │
+└─────────────────────────────────────┘
+```
 
-After `rails g archipelago:install`, you can scaffold frontend bootstrap wiring:
+## Building Actions
 
-```bash
-rails g archipelago:install:react
+Actions live in `app/islands/<component>/` and handle requests from island components.
+
+### Basic action
+
+```ruby
+# app/islands/team_members/add_member.rb
+class TeamMembers::AddMember < Archipelago::Action
+  param :team_id, :integer, required: true
+  param :email,   :string,  required: true, strip: true, downcase: true
+
+  authorize { current_user.teams.exists?(id: team_id) }
+
+  def perform
+    team = current_user.teams.find(team_id)
+    team.members.create!(email: email)
+
+    props(
+      members: team.members.map { |m| { id: m.id, email: m.email } }
+    )
+  end
+end
 ```
 
-The generator writes `.npmrc` with:
+### Action lifecycle
+
+1. **Param coercion** — declared params are validated and coerced into typed accessors
+2. **Authorization** — the `authorize` block runs (raises `Forbidden` on failure)
+3. **`perform`** — your business logic executes
+4. **Response** — returns `ok` (with props), `error` (with field errors), `redirect`, or `forbidden`
+
+### Response helpers
 
-```text
-@archipelago-js:registry=https://registry.npmjs.org
+```ruby
+def perform
+  props(members: [...])         # return updated props
+
+  redirect_to "/teams/#{team_id}" # or redirect
+
+  add_error(:email, "is already taken") # or add field errors
+end
 ```
 
-This keeps installs reliable across npm, Yarn classic, pnpm, and bun.
+### `current_user`
 
-By default this runs an interactive wizard with auto-detected defaults
-(bundler, TypeScript, package manager, and local monorepo path).
+Available in all actions, delegating to the configured user method:
 
-For esbuild apps, the wizard also enables auto-registry by default:
-- scans `app/javascript/islands/**/*.{js,jsx,ts,tsx}`
-- writes `app/javascript/archipelago/registry.generated.(js|ts)`
-- wires `package.json` esbuild scripts to run generator first
+```ruby
+def perform
+  project = current_user.projects.find(project_id)
+  # ...
+end
+```
 
-Useful options:
+### ActiveRecord::RecordInvalid
 
-```bash
-# disable prompts and use flags only
-rails g archipelago:install:react --interactive=false --bundler=esbuild --typescript=true
+Archipelago automatically catches `ActiveRecord::RecordInvalid` exceptions and maps them to field-level error responses.
+
+## Params DSL
+
+Declare expected parameters with type coercion, validation, and transformation:
+
+```ruby
+class TeamMembers::UpdateSettings < Archipelago::Action
+  param :name,     :string,  required: true, strip: true, min: 2, max: 100
+  param :email,    :string,  required: true, format: /\A[^@\s]+@[^@\s]+\z/
+  param :role,     :string,  required: true, in: %w[admin member viewer]
+  param :bio,      :string,  empty_as_nil: true
+  param :age,      :integer, min: 13, max: 150
+  param :score,    :float
+  param :active,   :boolean, default: true
+  param :tags,     :array,   of: :string
+  param :metadata, :json
+  param :starts_on, :date
+  param :due_at,    :datetime
+  param :nickname, :string, validate: ->(v) { "is offensive" if offensive?(v) }
+
+  # Params become methods: name, email, role, bio, etc.
+  def perform
+    user = current_user
+    user.update!(name: name, email: email, role: role, bio: bio)
+    props(user: serialize(user))
+  end
+end
+```
+
+### Supported types
+
+| Type | Coercion |
+|------|----------|
+| `:string` | `String(value)` |
+| `:integer` | `Integer(value)` |
+| `:float` | `Float(value)` |
+| `:boolean` | `true/1/"1"/"true"/"on"/"yes"` → `true`, etc. |
+| `:date` | `Date.parse(value)` |
+| `:datetime` | `Time.parse(value)` |
+| `:array` | Pass-through or `JSON.parse`, with optional `of:` typed elements |
+| `:json` | Pass-through or `JSON.parse` |
+
+### Validation options
+
+| Option | Description |
+|--------|-------------|
+| `required: true` | Rejects blank/nil values |
+| `default: value` | Fallback when missing (supports lambdas) |
+| `strip: true` | Strip whitespace (strings only) |
+| `downcase: true` | Downcase (strings only) |
+| `upcase: true` | Upcase (strings only) |
+| `in: [...]` | Value must be in the list |
+| `format: /regex/` | String must match pattern |
+| `min: n` | Minimum value or length |
+| `max: n` | Maximum value or length |
+| `empty_as_nil: true` | Treat `""` / whitespace-only as `nil` |
+| `of: :type` | Element type for arrays |
+| `validate: ->(v) { ... }` | Custom validator; return error string or nil |
+
+## Authorization
 
-# force TSX output
-rails g archipelago:install:react --typescript=true
+### Per-action authorization
 
-# disable auto-registry and keep manual registry map in entry file
-rails g archipelago:install:react --auto_registry=false
+Every action should define an `authorize` block:
 
-# install npm packages immediately
-rails g archipelago:install:react --install
+```ruby
+class TeamMembers::AddMember < Archipelago::Action
+  authorize { current_user.admin? }
 
-# install Archipelago packages from a local monorepo path
-rails g archipelago:install:react --install --local-monorepo-path=/absolute/path/to/cdx
+  def perform
+    # ...
+  end
+end
 ```
 
-Manual refresh command (if needed while a long-running watch is already running):
+When `authorize_by_default` is `true` (the default), actions without an `authorize` block raise `MissingAuthorization`.
+
+### Pundit adapter
+
+Include `Archipelago::PunditAdapter` for Pundit-style authorization:
+
+```ruby
+class TeamMembers::AddMember < Archipelago::Action
+  include Archipelago::PunditAdapter
+
+  param :team_id, :integer, required: true
+
+  def perform
+    team = current_user.teams.find(team_id)
+    authorize(team) # infers query from action class name
+    team.members.create!(email: email)
+    props(members: team.members.as_json)
+  end
+end
+```
+
+The adapter provides:
+- `authorize(record, query = nil)` — raises `Forbidden` if policy denies
+- `policy(record)` — returns the policy instance
+
+### CanCan adapter
+
+Include `Archipelago::CanCanAdapter` for CanCan-style authorization:
+
+```ruby
+class TeamMembers::AddMember < Archipelago::Action
+  include Archipelago::CanCanAdapter
+
+  param :team_id, :integer, required: true
+
+  def perform
+    team = current_user.teams.find(team_id)
+    authorize!(:manage, team)
+    team.members.create!(email: email)
+    props(members: team.members.as_json)
+  end
+end
+```
+
+The adapter provides:
+- `authorize!(action, record)` — raises `Forbidden` if ability denies
+- `current_ability` — returns the ability instance
+
+Configure the ability builder if you don't use a top-level `Ability` class:
+
+```ruby
+Archipelago.configure do |config|
+  config.current_ability = ->(user) { CustomAbility.new(user) }
+end
+```
+
+## Stream Authorization
+
+ActionCable streams can be authorized before subscription:
+
+```ruby
+Archipelago.configure do |config|
+  config.stream_authorizer = ->(connection:, stream_name:, params:) {
+    user = connection.current_user
+    # stream_name is e.g. "TeamMembers:42"
+    team_id = stream_name.split(":").last.to_i
+    user.teams.exists?(id: team_id)
+  }
+
+  # Reject all streams that don't pass through the authorizer
+  config.require_stream_authorization = true
+end
+```
+
+When `require_stream_authorization` is `true`, any stream without a configured authorizer is rejected. When `false` (default), streams are allowed unless an authorizer explicitly denies them.
+
+**Important:** If your streams carry tenant-specific or user-specific data, always configure a `stream_authorizer` or enable `require_stream_authorization`.
+
+## Configuration
+
+```ruby
+# config/initializers/archipelago.rb
+Archipelago.configure do |config|
+  config.root_namespace = "Islands"              # where actions live under app/islands/
+  config.current_user_method = :current_user     # controller method for current user
+  config.authorize_by_default = true             # require authorize blocks
+  config.strict_origin_check = false             # validate redirect origins
+  config.allowed_redirect_hosts = []             # allowed redirect hosts
+  config.stream_authorizer = nil                 # ActionCable stream auth lambda
+  config.require_stream_authorization = false    # reject unauthed streams
+  config.current_ability = nil                   # CanCan ability builder
+end
+```
+
+## Response Contract
+
+All action responses follow a standard JSON shape:
+
+```json
+// ok — updated props
+{ "status": "ok", "props": { ... }, "version": 1716000000000 }
+
+// error — field-level validation errors
+{ "status": "error", "errors": { "email": ["can't be blank"] } }
+
+// redirect
+{ "status": "redirect", "location": "/teams/1" }
+
+// forbidden
+{ "status": "forbidden" }
+```
+
+The `version` field is a monotonic timestamp used by the client to prevent stale broadcasts from overwriting newer data.
+
+## Streams & Broadcasting
+
+When a client sends the `X-Archipelago-Stream` header (or the legacy `__stream` param), successful action responses are automatically broadcast to all subscribers of that stream.
+
+On the client side, `useIslandProps({ stream: "TeamMembers:42" })` auto-subscribes to the stream and merges broadcast props into the component.
+
+## Supported Rails versions
+
+- Rails `>= 7.1`, `< 9.0`
+
+## Development
+
+```bash
+bundle install
+```
+
+### Run tests
+
+```bash
+bin/test                          # full suite
+bundle exec rake test:core        # core unit tests
+bundle exec rake test:rails       # rails integration tests
+```
+
+### Rails version matrix (Appraisal)
 
 ```bash
-yarn archipelago:registry
+bundle exec appraisal install
+bin/test-appraisal rails-7-1
+bin/test-appraisal rails-7-2
+bin/test-appraisal rails-8-1
 ```
+
+## Stability
+
+This library follows [Semantic Versioning](https://semver.org/). The public API surface — `Archipelago::Action`, the Params DSL, `authorize`, response helpers (`props`, `redirect_to`, `add_error`), configuration options, stream authorization, and the Pundit/CanCan adapter interfaces — is considered stable. Breaking changes will only occur in major version bumps.
+
+Internal modules, resolver internals, and the `raw_params` hash shape are not part of the public contract and may change in minor releases.
+
+## License
+
+MIT

data/test/archipelago/resolver_test.rb

@@ -77,4 +77,13 @@ class ResolverTest < ArchipelagoTestCase
       Archipelago::Resolver.new.resolve(component: "UnknownIsland", operation: "add_member")
     end
   end
+
+  def test_rejects_handler_that_does_not_inherit_from_action
+    not_an_action = Class.new
+    Archipelago.map "TeamMembers#not_action" => not_an_action
+
+    assert_raises(Archipelago::ResolutionError) do
+      Archipelago::Resolver.new.resolve(component: "TeamMembers", operation: "not_action")
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: archipelago-rails
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Archipelago