janela 0.5.0 → 0.7.0

data/lib/janela.rb

@@ -20,6 +20,10 @@ module Janela
   # Something the request asked for is not allowed here: a renderer, a
   # granularity, a limit or a filter. Rendered as 400.
   class BadRequest < Error; end
+  # The host has not said what may be read. Not rendered as anything: it is a
+  # setup mistake rather than a data condition, and dressing it as a 404 would
+  # hide the one line that fixes it (ADR 032).
+  class Unscoped < Error; end
 
   # Janela's controllers inherit from the host's, so the host's authentication
   # and authorisation apply to dashboards with no configuration.
@@ -37,9 +41,33 @@ module Janela
   # is for (ADR 021).
   mattr_accessor :silenced_checks, default: []
 
-  # Only models that declare a janela block are addressable over HTTP, keyed by
-  # the route key that appears in pane URLs (orders, sales_orders). Names are
-  # stored rather than classes so a reloaded model leaves nothing stale behind.
+  # What the host permits to be read, asked of its controller and never
+  # assumed. Janela refuses rather than reading everything, because a
+  # dashboard that quietly totals rows its reader may not see is the worst
+  # thing this library can do (ADR 032).
+  #
+  # Asked of the controller and never of self, because a helper runs on the
+  # view and a view cannot see a private controller method: when there were
+  # two copies of this question they disagreed about whether a host had
+  # answered it (#46). One copy, for that reason.
+  def self.scope(controller, model)
+    unless controller.respond_to?(:policy_scope, true)
+      raise Unscoped, "#{controller.class} defines no policy_scope, so Janela has not been " \
+                      "told what may be read of #{model.name}. Define it on " \
+                      "#{Janela.parent_controller}, returning the rows this visitor may see:\n\n" \
+                      "  private def policy_scope(model) = model.all\n\n" \
+                      "That line says every visitor may read every row of every model on a " \
+                      "dashboard. If that is not true here, return something narrower. " \
+                      "UPGRADING.md has the steps and docs/multi-tenancy.md has the wiring."
+    end
+
+    controller.send(:policy_scope, model)
+  end
+
+  # A model that declares a janela block is addressable over HTTP, and so is a
+  # subclass of one, keyed by the route key that appears in pane URLs (orders,
+  # sales_orders). Names are stored rather than classes so a reloaded model
+  # leaves nothing stale behind.
   def self.registry
     @registry ||= {}
   end
@@ -48,6 +76,18 @@ module Janela
     registry[model.model_name.route_key] = model.name
   end
 
+  # A subclass registers itself as it is created (ADR 031), so unlike a
+  # declaration it is not a host writing a line of code. It never takes a
+  # route key another class already holds: a host that gives a subclass its
+  # parent's model_name, so the two share a route and a form, would otherwise
+  # find the parent's URL answering with a subset of its rows.
+  def self.register_subclass(model)
+    route_key = model.model_name.route_key
+    return if registry.key?(route_key) && registry[route_key] != model.name
+
+    register(model)
+  end
+
   # Every model that declares a janela block, for a form that offers a choice
   # of them. Eager loading first, because a model nobody has referenced yet has
   # not registered. A name that no longer resolves is left out rather than

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -136,6 +136,7 @@ files:
 - db/migrate/20260915000001_create_janela_snapshots.rb
 - db/migrate/20260916000001_create_janela_frames.rb
 - db/migrate/20260916000002_create_janela_panes.rb
+- db/migrate/20260921000001_add_owner_to_janela_snapshots.rb
 - docs/decisions/001-built-to-be-forked.md
 - docs/decisions/002-measures-and-dimensions-over-ransack.md
 - docs/decisions/003-cross-filtering-with-turbo-frames.md
@@ -164,6 +165,12 @@ files:
 - docs/decisions/026-a-renderer-is-the-seam-and-html-comes-first.md
 - docs/decisions/027-the-gallery-is-a-host-page.md
 - docs/decisions/028-the-predicate-list-adr-025-named.md
+- docs/decisions/029-a-panes-frame-is-identified-by-who-it-is.md
+- docs/decisions/030-a-panes-src-belongs-to-turbo.md
+- docs/decisions/031-a-subclass-inherits-the-dashboard.md
+- docs/decisions/032-janela-will-not-read-a-model-it-cannot-scope.md
+- docs/decisions/033-a-snapshot-is-told-who-owns-it.md
+- docs/decisions/034-janela-will-not-freeze-a-scope-the-host-has-not-named.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -187,12 +194,22 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.5.0 bounds what a filter predicate can ask for (ADR 025). Most
-  applications need do nothing: a click already writes eq or in, both still
-  allowed. You need to act only if you pass a filter yourself using _cont,
-  _matches, _start, _end or another predicate outside a dimension's
-  allowlist, which now raises Janela::BadRequest instead of being quietly
-  answered.
+  Janela 0.7.0 stops guessing what may be read. Two things now refuse
+  rather than defaulting to every row, and both are quick to answer.
+
+  1. If your ApplicationController defines no policy_scope, every pane
+     raises Janela::Unscoped instead of totalling every row. Pundit
+     hosts and anyone following docs/multi-tenancy.md: nothing to do.
+     Everyone else writes one line (ADR 032).
+
+  2. If you schedule Janela::SnapshotJob, it now needs to be told what
+     rows to freeze: pass scope: :model_default, or subclass it and
+     override scope_for. A job already on your queue was serialised
+     without that argument and will raise when it performs, so drain it
+     or re-enqueue (ADR 034).
+
+  If you use snapshots, there is also a migration: janela_snapshots
+  gains a nullable owner (ADR 033).
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md