brut 0.0.20 → 0.0.22

data/{doc-src → brutrb.com}/keyword-injection.md

@@ -1,64 +1,74 @@
 # Keyword Injection
 
-Brut is desiged around classes and objects, as compared to modules and DSLs.  Almost everything you do when creating 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 initalizers and methods often need information from the request that Brut is managing.
 
-In a basic Rack or Sinatra app, you would access stuff like query parameters or the session by using Rack's API.  This can be tedious
-and error-prone.  Brut will inject certain values into your class based on the keyword arguments of the initializer or method.
+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.
 
-For example, a {file:doc-src/pages.md Page} requires you to implement an initializer. That initializer's keyword arguments define what
+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.
+
+## 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:
 
-    page "/widgets/:id"
+```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:
 
-    class WidgetsByIdPage < AppPage
-      def initialize(id:)
-        @widget = DB::Widget.find(id)
-      end
-    end
+```ruby
+class WidgetsByIdPage < AppPage
+  def initialize(id:)
+    @widget = DB::Widget.find(id)
+  end
+end
+```
 
-There are many more values that can made available.  For example, suppose you accept the query string parameter "compact" that
-controls some rendering of the page.  To access it, declare it as a keyword arg (being sure to set a default value since it may not be available):
+If the page requires access to the session, it can declare that:
 
-    class WidgetsByIdPage < AppPage
-      def initialize(id:, compact: false)
-        @widget  = DB::Widget.find(id)
-        @compact = compact
-      end
-    end
+```ruby {2,4}
+class WidgetsByIdPage < AppPage
+  def initialize(id:, session:)
+    @widget       = DB::Widget.find(id)
+    @current_user = session.current_user
+  end
+end
+```
+
+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
+### 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.
+* `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.
+* `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 {file:doc-src/forms.md Forms}.
-* Any query string paramter - Remember, these should have default values or Brut will raise an error if they are not provided.
+* `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:
+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
+* `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
@@ -88,42 +98,53 @@ prevent this in the future.
 
 You can also use the request context to put your own data that can be injected.
 
-## Injecting Custom Data
+### Injecting Custom Data
 
-The general lifecycle of a request is that any before hook is run, then the page or action is triggered, then after actions.  Thus, to
-inject your own data, such as the currently authenticated visitor, you would use a before hook:
+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.
 
-    class AppSession < Brut::FrontEnd::Session
-      def logged_in?
-        !!self.authenticated_account
-      end
-      def authenticated_account
-        # look up the account data model 
-        # based on e.g. self[:account_id]
-      end
-    end
+For example, here is how you might inject the currently logged-in account based on the session:
 
-    class AuthBeforeHook < Brut::FrontEnd::RouteHook
-      def before(request_context:,session:,request:,env:)
-        if session.logged_in?
-          request_context[:authenticated_account] = session.authenticated_account
-        end
-        continue
-      end
+```ruby
+class AuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:)
+    if session.authenticated_account
+      request_context[:authenticated_account] = session.authenticated_account
     end
+    continue
+  end
+end
+```
 
-Once you do this, you can use `authenticated_account:` as a keyword argument to any page, handler, or global component:
+Note that the value is only injected if it exists.  It's important not to inject `nil` for values that
+don't exist.
 
-    class DashboardPage < AppPage
-      def initialize(authenticated_account:)
-        @widgets = authenticated_account.widgets # e.g.
-      end
-    end
+You may be thinking that this particular example is unnecessary. You could simply inject `session:` and
+call `session.authenticated_account`:
+
+```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
+  def initialize(authenticated_account:)
+    @widgets = authenticated_account.widgets # e.g.
+  end
+end
+```
 
-While this won't handle authorization for you, you can be sure that when `DashboardPage` is used, there is an `authenticated_account`
-available.
+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
+### `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.
@@ -133,17 +154,18 @@ injecting `nil` when you actually intend to not have a value.
 
 For example, the `AuthBeforeHook` above, you could implement it like so:
 
-      request_context[:authenticated_account] = session.authenticated_account
+```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.
+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.
 
-## When Values Aren't Available
+### 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.
@@ -158,13 +180,30 @@ parameters should always have a default value, even if it's `nil`.
 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).
 
-See {file:docs-src/route-hooks.md}
+See [route hooks](/hooks).
+
+### 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.
+
+In particular, A basic `request_context` is setup per test and injected into the Thread local storage. This means
+that if your test should trigger a codepath that *does* cause Brut to use keyword injection, useful values will
+be injected.
+
+For your tests, however, you should pass in directly what you need:
 
-## Design For Injection
+```ruby
+page = WidgetsByIdPage.new(id: widget.id, session: empty_session)
+```
+
+## Recommended Practices
 
 Consider a method like so:
 
-    def create_widget(name:, organization: nil, quantity: 10)
+``` ruby
+def create_widget(name:, organization: nil, quantity: 10)
+```
 
 Outside of Brut, the way to interpret this arguments is as follows:
 
@@ -172,12 +211,27 @@ Outside of Brut, the way to interpret this arguments is as follows:
 * `organization` is optional
 * `quantity` has a default value of 10 if not provided
 
-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:
+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:
 
 * **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)
   - Otherwise, do not provide a default for the keyword
+* **Design for non-`nil` values instead of allowing `nil` and checking for it**
+  - If a page needs, say, the currently logged-in user, set that up as injectible with no default.
+  - If a codepath creates that page without the logged-in user, you will get a very obvious error and
+    can figure out how it happened. Your page's code doesn't need to figure out what to do with `nil`
 * **Do not inject `nil` into the request context.** When your code requires a value for a keyword, you want to rely on that value being non-nil.  Thus, avoid injecting `nil` into the request context. Brut will allow it as a sort-of escape hatch, but you should design your app to avoid it
 * **Be careful injecting global data.**  The request context instance is per request, but you could certainly put global data into it. For example, you may put an initialized API client into the request context as a convieniece. **Be careful** because your app is multi-threaded.  Any object that is not scoped to the request must be thread-safe.
+
+## Technical Notes
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_Last Updated May 7, 2025_
+
+Keyword injection is currently implemented in a few places and not available via public API.  It could be useful
+as an API and it will be exposed at some point. For now, it's only available for Brut-managed classes as
+documented here.

data/brutrb.com/markdown-examples.md

@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````md
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

data/brutrb.com/middleware.md

@@ -0,0 +1,80 @@
+# Middleware
+
+Brut supports Rack Middleware.
+
+## Overview 
+
+Similar to [route hooks](/hooks), Brut supports Rack Middleware, which is a lower-level way of modifying a
+request or changing behavior.
+
+Middleware is recommended if what you want to do is not dependent on your application's code or classes
+and is relatively simple.
+
+To use a middleware, create the class in `app/src/front_end/middleware/`. You are encouraged to extend
+`Brut::FrontEnd::Middleware`, however this is an empty class currently. It could grow to have helper
+methods you'll find useful.
+
+The class itself should conform to Rack's specification, which is typically that it will be given the Rack
+"app" in the initializer, and then have a method `call` which will be given the Rack environment.
+
+Here's a middleware that adds a tag to the environment for paths that are "special" to our app, which in
+this case means they start with `/special`:
+
+```ruby
+class TagSpecialPathsMiddleware < Brut::FrontEnd::Middleware
+
+  def initializer(app)
+    @app = app
+  end
+
+  def call(env)
+    if env["PATH_INFO"] =~ /^\/special\//
+      env["app.special_path"] = true
+    end
+    @app.call(env)
+  end
+end
+```
+
+To use this middleware, call `use` with the class name as a string inside `App`:
+
+```ruby
+class App < Brut::Framework::App
+
+  # ...
+
+  use :TagSpecialPathsMiddleware
+
+  # ...
+end
+```
+
+Don't use the actual class as this can create load order issues.
+
+## Testing
+
+Like hooks, Rack middleware can be tested as a normal class.  That said, you are encouraged to test the
+middleware as part of an end-to-end test if possible, since this will ensure it's configured properly in
+the context of your app.
+
+## Recommended Practices
+
+Middleware should be used when its logic can be entirely based on the Rack environment passed-in.  While
+your database models and other classes should be available, excessive use of your domain logic in a
+middleware can create a confusing situation.
+
+## Technical Notes
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_Last Updated June 12, 2025_
+
+Route hooks and Middlewares do not share implementations, however they are similar in concept.  These
+concepts may be unified in the future.
+
+`use` and the way Middleware behaves follows Sinatra's implementation as Brut is currently based on
+Sinatra. This may not always be the case, however as things change, we will do our best to ensure the
+semantics remain the same.  Nevertheless, it's advisable to have end to end tests assert the behavior of
+your configured middleware and not just a unit test of the class itself.

data/brutrb.com/not-released.md

@@ -0,0 +1,5 @@
+# Brut is Not Released Software
+
+> [!WARNING]
+> Brut is not considered released.  It is still in development and some of what is in this doc
+> site is inaccurate.