brut 0.0.28 → 0.1.0

data/brutrb.com/keyword-injection.md

@@ -1,77 +1,67 @@
 # Keyword Injection
 
-Brut is desiged around classes and objects, as compared to modules and DSLs.  Almost everything you do when building your app is to create a class that has an initializer and implements one or more methods.  But, these initalizers and methods often need information from the request that Brut is managing.
+Brut is desiged around classes and objects, as compared to modules and DSLs.  Almost everything you do when building your app is to create a class that has an initializer and implements one or more methods.  But, these classes often need information from the request that Brut is managing.
 
-In a basic Rack or Sinatra app, you would access this information via Rack's API, which is essentially a `Hash` of whatever. It's error-prone and requires consulting documentation, source code, or runtime information to figure out what's stored where.
+In a basic Rack or Sinatra app, you would access this information via Rack's API, which is essentially a Hash of Whatever. It's error-prone and requires consulting documentation, source code, or runtime information to figure out what's stored where.
 
 Brut can instead inject these values explicitly into the classes of yours it creates.  It does this based on the
-names of keyword arguments declared by your class' intializer or a template method Brut will call.
+names of keyword arguments declared by your class' intializer.
 
 ## Overview
 
-For example, a [Page](/pages) requires you to implement an initializer. That initializer's keyword arguments define what
-information is needed. Brut provides that information when it creates the object. This is a form of dependency injection and it can simplify your code if used effectively.
-
-Consider this route:
-
-```ruby
-page "/widgets/:id"
-```
-
-Brut will expect to find `WidgetsByIdPage`.  Your initializer can declare `id:` as a keyword arg and this will be passed when the
-class is created:
+A [Page](/pages) may need the session, flash, HTTP headers, query string parameters, or placeholder values from the URI.  These can all be provided by declaring them as keyword arguments to the page's initializer:
 
 ```ruby
-class WidgetsByIdPage < AppPage
-  def initialize(id:)
-    @widget = DB::Widget.find(id)
+clas WidgetsByIdPage < AppPage
+  def initialize(id:,                # ":id" from /widgets/:id
+                 session:,           # AppSession instance for this request
+                 flash:,             # Flash for this request
+                 http_user_agent:,   # Value of User-Agent header
+                 compact:)           # query string param "compact"
+
+    # ...
   end
 end
 ```
 
-If the page requires access to the session, it can declare that:
-
-```ruby {2,4}
-class WidgetsByIdPage < AppPage
-  def initialize(id:, session:)
-    @widget       = DB::Widget.find(id)
-    @current_user = session.current_user
-  end
-end
-```
+Brut uses this technique in multiple places.  It allows you to design classes whose
+dependencies are clear and explicit, but without having to dig around into hashes or
+manually construct higher-level objects.
 
-Because `session:` is a required argument, Brut cannot instantiate the page without it, so it will always be
-passed in and availbale.
 
 ### Standard Injectible Information
 
 In any request, the following information is available to be injected:
 
-* `session:` - An instance of your app's `Brut::FrontEnd::Session` subclass for the current visitor's session.
-* `flash:` - An instance of your app's `Brut::FrontEnd::Flash` subclass.
-* `xhr:` - true if this was an Ajax request.
-* `body:` - the body submitted, if any.
-* `csrf_token:` - The current CSRF token.
-* `clock:` - A `Clock` to be used to access the current time in the visitor's time zone.
-* `http_*` - any parameter that starts with `http_` is assumed to be for an HTTP header. For example, `http_accept_language` would be
-given the value for the "Accept-Language" header.  See the section on HTTP headers below.
-* `env:` - The Rack env.  This is discouraged, but available if you can't get what you want directly
-
-Depending on the context, other information is available:
-
-* `form:` - If a form was submitted, this is the `Brut::FrontEnd::Form` subclass containing the data. See [Forms](/forms).
-* Any query string paramter - Note that if these conflict with existing Brut values, the behavior is undefined.  Name your query string parameters carefully. These should have default values or your page won't work if they are omitted.
-* Any route parameter - These should not have default values, since they are required for Brut to match the route.
-
-A `Brut::FrontEnd::RouteHook` is slightly different. Only the following data is available to be injected:
-
-* `request_context:` - The current request context, thought it may be `nil` depending on when the hook runs
-* `session:` - An instance of your app's `Brut::FrontEnd::Session` subclass for the current visitor's session.
-* `request:` - The Rack request
-* `response:` - The Rack response
-* `env:` - The Rack env.
-
-### HTTP Headers
+| Value                      | Always Present?                                                                                                                                                                                                    | Description                                                                                     |
+| ---                        | ---    | ----                                                                                            |
+| `session:`                 | ✅ Yes | An instance of your app's `Brut::FrontEnd::Session` subclass for the current visitor's session. |
+| `flash:`                   | ✅ Yes | An instance of your app's `Brut::FrontEnd::Flash` subclass.                                                                                                                                                        |
+| `xhr:`                     | ✅ Yes | true if this was an Ajax request.                                                                                                                                                                                  |
+| `body:`                    | ✅ Yes | the body submitted, if any.                                                                                                                                                                                        |
+| `csrf_token:`              | ✅ Yes | The current CSRF token.                                                                                                                                                                                            |
+| `clock:`                   | ✅ Yes | A `Clock` to be used to access the current time in the visitor's time zone.                                                                                                                                        |
+| `http_*`                   | ❌ No  | any parameter that starts with `http_` is assumed to be for an HTTP header. For example, `http_accept_language` would be given the value for the "Accept-Language" header.  See the section on HTTP headers below. |
+| `rack_request_*:`          | ❌ No  | Any value from the [`Rack::Request`](https://rubydoc.info/gems/rack/3.1.16/Rack/Request) or, more likely, from the [`Helpers`](https://rubydoc.info/gems/rack/3.1.16/Rack/Request/Helpers) module.                 |
+| `env:`                     | ✅ Yes | The Rack env.  This is discouraged, but available if you can't get what you want directly                                                                                                                          |
+| `form:`                    | ❌ No  | The [form](/forms) that was submitted, for [handlers](/handlers) only                                                                                                                                              |
+| Any query string parameter | ❌ No  | For [pages](/pages) only                                                                                                                                                                                           |
+| Any route placeholder      | ✅ Yes | For [pages](/pages) and [handlers](/handlers)                                                                                                                                                                      |
+
+#### Route Hooks
+
+[Route hooks](/hooks) are slightly different.  They have access to only these
+values:
+
+| Name               | Always Present? | Description                                                                                                                      | 
+| ---                | ---             | --- |
+| `request_context:` | ❌ No           | The current `Brut::FrontEnd::RequestContext`, thought it may be `nil` if the hook runs before `Brut::FrontEnd::InlineSvgLocator` |
+| `session:`         | ✅ Yes          | An instance of your app's `Brut::FrontEnd::Session` subclass for the current visitor's session.                                  |
+| `request:`         | ✅ Yes          | The Rack request                                                                                                                 |
+| `response:`        | ✅ Yes          | The Rack response                                                                                                                |
+| `env:`             | ✅ Yes          | The Rack env.                                                                                                                    |
+
+#### HTTP Headers
 
 Since any header can be sent with a request, Brut allows you to access them, including non-standard ones.  Rack (which is based on CGI), provides access to all HTTP headers in the `env` by taking the header name, replacing dashes ("-") with underscores ("\_"), and prepending `http_` to the name, then uppercasing it.  Thus, "User-Agent" becomes `HTTP_USER_AGENT`.
 
@@ -88,22 +78,14 @@ things:
   - If the header was not provided, no value is injected, and your code will receive the default value.
   - If the header *was* provided, it's value is injected, even if it's the empty string.
 
-### Ordering and Disambiguation
-
-You are discouraged from using builtin keys for your own data or request parameters.  For example, you should not have a query string
-parameter named `env` as this conflicts with the builtin `env` that Brut will inject.
-
-Since you can inject your own data (see below), you are free to corrupt the request context.  Please don't do this. Brut may actively
-prevent this in the future.
-
-You can also use the request context to put your own data that can be injected.
-
 ### Injecting Custom Data
 
-The correct place to inject your own data into the request is in a [before hook](/hooks).  When you
-configure a before hook, it will run after Brut's internal
-`Brut::FrontEnd::RouteHooks::SetupRequestContext`, which ensures the request context exists and is ready
-for use.
+The true power of keyword injection is that you can store your own data into the
+request context and have it injected into classes when Brut instantiates them.
+
+The place to do this is in a [before hook](/hooks), since that happens before any
+page or handler is created, but *after* the `Brut::FrontEnd::RequestContext` is
+created (which is where all of this information is stored).
 
 For example, here is how you might inject the currently logged-in account based on the session:
 
@@ -118,71 +100,44 @@ class AuthBeforeHook < Brut::FrontEnd::RouteHook
 end
 ```
 
-Note that the value is only injected if it exists.  It's important not to inject `nil` for values that
-don't exist.
+Note that the value is only injected if it exists.  It's important not to inject `nil` for values that don't exist.
 
-You may be thinking that this particular example is unnecessary. You could simply inject `session:` and
-call `session.authenticated_account`:
+With this in place, any page that requires an authenticated account can declare it:
 
 ```ruby
-class DashboardPage < AppPage
-  def initialize(session:)
-    @widgets = session.authenticated_account.widgets # e.g.
-  end
-end
-```
-
-If `DashboardPage` requires an authenticated account, by only injecting the session, you'll need to handle the case where `session.authenticated_account` is `nil`.  Instead, if you configure the `AuthBeforeHook` as above, then inject `authenticated_account`, you avoid the need for this logic:
-
-```ruby
-class DashboardPage < AppPage
+class PreferencesPage < AppPage
   def initialize(authenticated_account:)
-    @widgets = authenticated_account.widgets # e.g.
+    # ...
   end
 end
 ```
 
-Because `AuthBeforeHook` never injects `nil`, `DashboardPage` can rely on `authenticated_account` always being present.  Further, if a visitor tried to access `/dashboard_page` without having been authenticated, Brut would be unable to create an instance of `DashboardPage` and generate an error.
-
-### `nil` and Empty Strings
-
-When a keyword argument has no default value, Brut will require that value to exist and be available for injection. If the keyword is
-not one of the canned always-available values, it will look in the request context, then in the query string.
+If the request context has no value for `authenticated_account`, the page cannot be
+instantiated.  Thus, the page's code can always rely on a non-`nil` value for
+`authenticated_account` (provided you don't inject `nil`).
 
-If the request has the keyword as a key, *it will inject whatever value it finds, including `nil`*.  In general, you should avoid
-injecting `nil` when you actually intend to not have a value.
-
-For example, the `AuthBeforeHook` above, you could implement it like so:
-
-```ruby
-request_context[:authenticated_account] = session.authenticated_account
-```
-
-The problem is that if the visitor is not logged in, the `:authenticated_account` *will* have a value, and that value will be `nil`. This is almost certainly not what you want.
-
-For query string parameters, the HTTP spec says that they are strings.  Thus, if a query string parameter is present in ther request
-URL, it will *always* have a value and *never* be `nil`.  If the paramter doesn't have a value after the `=` (e.g. for `foo` in `?foo=&bar=quux`), the value will be the empty string.
-
-This means you must write code to explicitly handle the cases you care about.
+> [!WARNING]
+> Do not inject `nil` into the request context.  Brut currently allows
+> it, but may prevent it in a future update. `nil` is no good for nobody.
 
 ### When Values Aren't Available
 
 When a value is not available for injection, and the keyword doesn't provide a default, Brut will raise an error.  This is because
 such a situation represents a design error.
 
-For example, the `DashboardPage` above requires an `authenticated_account`.  Your app should never route a logged-out visitor to that
-page.  This allows the `DashboardPage` to avoid having to check for `nil` and figure out what to do.
-
-This is most relevant for query string parameters, since they can be easily manipulated by the visitor in their browser.  Query string
-parameters should always have a default value, even if it's `nil`.
+The tables above document which values should always be available. You should never
+provide a default value for these, e.g. `session:` or `env:`. For values that are
+not always available, you should provide a default value unless you are sure there
+will be no routing to the page or handler without the value set.
 
-*Path* parameters (like `:id` in `WidgetsByIdPage`) should *never* have a default value as their absence means a different URL was
-requested.  For example, `/widgets` would trigger a `WidgetsPage`. *Only* if the `:id` path parameter is present would the
-`WidgetsByIdPage` be triggered, so it's safe to omit the default value for `id:` (and pointless to include one).
+This is most important for query string parameters.  Since a user can easily
+manipulate these, if your page accepts, say, the parameter `use_detailed_view`, but
+that parameter isn't present, Brut will not be able to instantiate your page unless
+`use_detailed_view:` has a default value in the initializer's keyword arguments.
 
 See [route hooks](/hooks).
 
-### Testing
+## Testing
 
 Brut will not create your classes in a test.  Instead, you must pass in the values you want.  There are various
 helpers in `Brut::SpecSupport` to create blank or empty versions of the special classes.
@@ -213,6 +168,9 @@ Outside of Brut, the way to interpret this arguments is as follows:
 
 Any method or intializer that will be keyword-injected should be designed with this in mind.  Thus, the following guidelines will be helpful in managing your app:
 
+* **Do not provide default values when Brut documents the value is always
+available**
+  - If your page needs the session, it will always be there. Don't default `session:` to some other value (especially `nil`!)
 * **Choose arguments based on the needs of the class:**
   - If a value is optional, default it to either `nil` or a symbol that indicates what happens when the value is omitted
   - If an optional value has a default, use that (this should be rare for pages, handlers, components, and hooks)

data/brutrb.com/layouts.md

@@ -6,11 +6,13 @@ different pages.  Conceptually, they are the same as a Rails layout.  Technicall
 ## Overview
 
 Your app should include `app/src/front_end/layouts/default_layout.rb`. The name
-"default" is special, in that all pages will use this layout by default.
+"default" isn't special, it's just what the `layout` method from
+`Brut::FrontEnd::Page` returns.
 
-Since a layout is a Phlex component, its HTML is generated from `view_template`, and
-it is expected to have exactly one `yield`, where the page's content will be
-inserted.
+A layout is a Phlex component that's expected to have a single call to `yield` in
+its `view_template` method.
+
+Here is the `DefaultLayout` provided to new Brut apps:
 
 ```ruby {33}
 class DefaultLayout < Brut::FrontEnd::Layout
@@ -53,53 +55,18 @@ class DefaultLayout < Brut::FrontEnd::Layout
 end
 ```
 
-### Maintaining Layouts
-
-You are free to manage this how you like, however a few components inside the
-`<head>` and `<body>` that are important to keep:
-
-* `Brut::FrontEnd::Components::PageIdentifier` includes a `<meta>` tag with the page's name in it, which is handy for managing your end-to-end tests.
-* `Brut::FrontEnd::Components::I18nTranslations` includes translatsion for common client-side constraint violations.  See [Forms](/forms), [I18n](/i18n), and [JavaScript](/javascript) for more details on how this is used.
-* `Brut::FrontEnd::Components::Traceparent` ensures that the OpenTelemetry *traceparent* is available so when client-side telemetry is reported back to the server, it can be connected to the request that initiated it.
-* The `<brut-tracing>` element collects the client-side telemetry and sends it back
-to the server.
-
-### Creating Alternate Layouts
-
-The way each page knows to use `DefaultLayout` is due to the `layout` method of
-`Brut::FrontEnd::Page`, which returns `"default"`.  The return value of `layout` is
-used to figure out the name of the layout class.
-
-You can set up your own by overriding `layout`:
-
-```ruby
-class MyOtherPage < AppPage
-  def layout = "other_design"
-
-  # ...
-
-end
-```
+You will likely want to customize what's in your layout, but a few components
+included by default are important for other features of Brut:
 
-Brut will expect the class `OtherDesignLayout` to exist and provide HTML.  Based on
-Zeitwerk's conventions, that class should be in
-`app/src/front_end/layouts/other_design_layout.rb`.
+| Component | Purpose
+|---|---|
+| `Brut::FrontEnd::Components::PageIdentifier` | Creates a `<meta>` tag with the page's name in it, which is handy for managing your end-to-end tests. |
+| `Brut::FrontEnd::Components::I18nTranslations` | Includes translatsion for common client-side constraint violations.  These are used by `<brut-cv-messages>` and `,brut-cv>`. See [Forms](/forms), [I18n](/i18n), and [JavaScript](/javascript) for more details |
+| `Brut::FrontEnd::Components::Traceparent` | Includes the OpenTelemetry *traceparent* on the page so that client-side telemetry is reported back to the server.  See `<brut-tracing>` and [observability](/instrumentation) |
+| `<brut-tracing>` / `brut_tracing` | Custom element that collects the client-side telemetry and sends it back to the server. See [observability](/instrumentation) |
 
-### No Layout
-
-If you don't want a layout, you are encouraged to creat a blank layout, for example:
-
-```ruby
-class BlankLayout < Brut::FrontEnd::Layout
-  def view_template
-    yield
-  end
-end
-
-# use like so:
-
-def layout = "blank"
-```
+See [creating alternate layouts](/recipes/alternate-layouts) and [blank
+layouts](/recipes/blank-layouts) for customization options.
 
 ## Testing
 
@@ -109,9 +76,10 @@ needs complex logic, you are encouraged to extract that to a
 
 ## Recommended Practices
 
-Keep your layouts as simple as you can.
-
-
+Layouts can use components, just keep in mind that any data a component needs must
+be passed to its initializer. Since the layout doesn't have access to the page, this
+implies that components used in your layout must either not require dynamic data or
+be [global components](/components#global-components)
 
 ## Technical Notes
 

data/brutrb.com/lsp.md

@@ -18,6 +18,6 @@ which Brut has done, and some you will need to do.
 |---|---|---|
 | Paths inside Docker Must Match Your Computer | When an LSP server communicates about a file, it does so with a path. That means that paths inside the Docker container must be the same as those on your computer.  Brut achievecs this by using `${CWD}` inside `docker-compose.dx.yml` | ✅ |
 | Third party libraries must *also* be installed in a path that is the same in both places | When jumping to a definition, the LSP server will again use paths, which must match.  Because Node modules are installed local to your app, they already work.  Ruby Gems, however, are configured to be installed in `local-gems` in your app.  Brut should've added this to `.gitignore` and setup everything inside Docker to use it. | ✅ |
-| Your editor must use `dx/exec` to execute LSP commands | Your editor will need to know that the LSP servers are running inside Docker.  If your editor allows configuring the commands used to do this, you must prefix them with `dx/exec bashc -lc`. See [my blog post](https://naildrivin5.com/blog/2025/06/12/neovim-and-lsp-servers-working-with-docker-based-development.html) for details. | ❌ |
+| Your editor must use `dx/exec` to execute LSP commands | Your editor will need to know that the LSP servers are running inside Docker.  If your editor allows configuring the commands used to do this, you must prefix them with `dx/exec`. See [my blog post](https://naildrivin5.com/blog/2025/06/12/neovim-and-lsp-servers-working-with-docker-based-development.html) for details. | ❌ |
 | Other languages or plugins to existing LSP servers | I haven't used these, so no idea how well they work. | ❌ |