brut 0.0.20 → 0.0.22

data/brutrb.com/images/spa.dot

@@ -0,0 +1,19 @@
+digraph G {
+
+  Node[fontname="Helvetica"]
+  Edge[fontname="Baskerville"]
+
+  ShouldBeSPA              -> SessionMoreThan10Minutes
+  SessionMoreThan10Minutes -> No [label="No"]
+  SessionMoreThan10Minutes -> TenUpdatesPrimaryData [label="Yes"]
+  TenUpdatesPrimaryData    -> No [label="No"]
+  TenUpdatesPrimaryData    -> Maybe [label="Yes"]
+ 
+  ShouldBeSPA              [ shape=rect label="Should this App\nby a Single-Page-App (SPA)?"]
+  No                       [ shape=octagon]
+  Maybe                    [ shape=circle]
+  SessionMoreThan10Minutes [ shape=diamond label="Sessions last\nlonger than\n10 minutes?\n"]
+  TenUpdatesPrimaryData    [ shape=diamond label="More than 10\nupdates to primary\nuser data?"]
+  
+  { rank=same; SessionMoreThan10Minutes; No }
+}

data/brutrb.com/images/workspace-protocol.dot

@@ -0,0 +1,44 @@
+digraph G {
+
+  rankdir="LR"
+  nodesep=0.55
+  compound=true
+  node[shape=box fontname=avenir]
+
+  Setup[label=<
+    <FONT face="avenir">Setup</FONT>
+    <br/>
+    <FONT face="Courier New">bin/setup</FONT>
+  >]
+  Run[label=<
+    <FONT face="avenir">Run</FONT>
+    <br/>
+    <FONT face="Courier New">bin/dev</FONT>
+  >]
+  Test[label=<
+    <FONT face="avenir">Test</FONT>
+    <br/>
+    <FONT face="Courier New">bin/test</FONT>
+  >]
+  CI[label=<
+    <FONT face="avenir">Test</FONT>
+    <br/>
+    <FONT face="Courier New">bin/ci</FONT>
+  >]
+  Code[label=<
+    <FONT face="avenir">Code</FONT>
+    <br/>
+    <FONT face="Baskerville">Write Code</FONT>
+    <br/>
+    <FONT face="Courier New">bin/db</FONT>
+    <br/>
+    <FONT face="Courier New">bin/scaffold</FONT>
+  >]
+  Setup -> Run
+  Setup -> Code
+  Run   -> Code
+  Code  -> Test
+  Test  -> Code
+  Test  -> CI
+  { rank=same; Run; Code; }
+}

data/brutrb.com/index.md

@@ -0,0 +1,36 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Brut RB"
+  text: "Raw Ruby Web Apps"
+  tagline: Standards-based, No-nonsense, HTML-first, Low Ceremony
+  image:
+    src: /images/logo.png
+    alt: "A Ruby gemstone embedded into a concrete, brutalist building"
+  actions:
+    - theme: brand
+      text: "Brut is Not Yet Released"
+      link: /not-released
+    - theme: brand
+      text: "Getting Started"
+      link: /getting-started
+    - theme: alt
+      text: Conceptual Overview
+      link: /overview
+
+features:
+  - title: Standards-Based
+    icon:  📄
+    details: "Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"
+  - title: Convention-Oriented
+    icon: 🎚️
+    details: "In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."
+  - title: Objects and Methods
+    icon: 💻
+    details: "Author classes to create objects on which to call methods. Nothing fancy."
+  - title: Builds on Community Libraries
+    icon: 🏘️
+    details: "Sequel, Phlex, I18n, RSpec. They do it best"
+---

data/brutrb.com/instrumentation.md

@@ -0,0 +1,183 @@
+# Instrumentation and Observability
+
+Brut has built-in support for OpenTelemetry, which is an open standard used by many observability vendors
+to allow you to understand the behavior of your app in production.  Brut also includes a configuration for
+the [otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer/), which allows you to see
+instrumentation in development.
+
+## Overview
+
+### Why Instrument?
+
+In production, you'll need to know what your app is doing and how well it's working.  Historically, logs
+can provide this information in a roundabout way. Over the last many years, Application Performance
+Monitoring (APM) vendors like New Relic and Data Dog allowed developers to see much richer detail about
+how an app is working.
+
+You could see, for example, the 95th percentil of your dashboard controller's performance, or the top 10
+slowest SQL statements your app is executing.  OpenTelemetry attempts to unify the API used to communicate
+this information from your app to your chosen vendor, and most vendors support it.
+
+Instrumentation, then, is a way to record what your app is doing, how long its taking, and perhaps even
+why it's doing what it's doing, down to a very specific level.  If properly configured, you could examine
+the performance of the app for a particular user on a particular day.
+
+### Setting up Instrumentation
+
+Brut automatically sets up OpenTelemetry (OTel) tracing.  The primary interface you will use is
+`Brut::Instrumentation::OpenTelemetry`, which is available via `Brut.container.instrumentation`.  We'll
+discuss that in a moment.
+
+To configure the specifics of where the traces wil go, the OTel gem uses environment variables:
+
+| Variable                             | Value                      | Purpose                                                                                                                                                         |
+|--------------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT`        | Depends on environment     | Where to send the tracers. This is provided by your vendor, but is `http://otel-desktop-viewer:4318` in development                                             |
+| `OTEL_EXPORTER_OTLP_HEADERS`         | Depends on vendor          | Your vendor may ask you to set this. It often contains identifying information or API keys                                                                      |
+| `OTEL_EXPORTER_OTLP_PROTOCOL`        | http/protobuf              | Your vendor may request a different protocol, but protobuf is common and supported by otel-desktop-viewer                                                       |
+| `OTEL_LOG_LEVEL`                     | debug                      | Useful when setting everything up to understand why things aren't working if they aren't working                                                                |
+| `OTEL_RUBY_BSP_START_THREAD_ON_BOOT` | false                      | Deals with esoteric issues with Puma. See [this GitHub issue](https://github.com/open-telemetry/opentelemetry-ruby/issues/462) for the details.
+| `OTEL_SERVICE_NAME`                  | Your app's `id` from `App` | Identifiers your app's name to the vendor                                                                                                                       |
+| `OTEL_TRACES_EXPORTER`               | otlp                       | Configures the class inside the OTel gem that will export the instrumentation to the vendor. If you omit this, Brut will log the instrumentation to the console |
+
+When you created your Brut app, your `.env.development` and `.env.test` should have values for all these
+environment variables that will send instrumentation to the otel-desktop-viewer that was also configured.
+
+If you run your app using `bin/dev` and use the app for a bit, then go to `http://localhost:8000`, you
+will see the otel-desktop-viewer UI and can browser the spans and traces sent by Brut.
+
+
+### What is Instrumented By Default
+
+Brut attempts to automatically instrument useful things so you don't have to do anything to start getting
+data.  Brut will attempt to conform to standard semantics for HTTP requests and SQL statements.
+
+Here is a non-exhaustive list of what Brut automatically instruments:
+
+* How long each page or handler request takes
+* CLI execution time
+* Time to rebuild the schema for tests
+* Time to run tests
+* Time to apply migrations
+* Time spent inside a route hook
+* The locale detected from the browser
+* The layout class used when rendering a page
+* If a requested path is owned by Brut or not
+* Ignored parameters on all form submissions
+* How long reloading takes in development
+* CSP reporting results
+
+### Adding Your Own Instrumentation
+
+You can add instrumentation in a few ways:
+
+* *Spans* record a block of code. They are shown as a sub-span if one is already in effect.  When you
+create a span, that means it will be shown in the context of the HTTP request.
+* *Attributes* can be added to the current span to provide more context about what is happening. For
+example, the HTTP request method is an attribute of the span used for the HTTP request.  These attributes
+allow for sophisticated querying in the vendor's UI.
+* *Events* record things that happen and metadata about that thing. These are like log statements. They
+are associated with the span you are in when you add the event.
+
+These can all be added via `Brut.container.instrumentation`, which is a
+`Brut::Instrumentation::OpenTelemetry` instance.
+
+These methods are available:
+
+* `span(name,**attributes,&block)` - Create a new span around the block yielded.
+* `add_attributes(attributes)` - Add attributes to the current span. These will be prefixed with your
+app's prefix so it's clear in the observability UI that they are for your app and not standard.
+* `add_event(name,**attributes)` - Add an event with optional attributes for the current span.
+* `record_exception(ex,attributes=nil)` - Record an exception that was caught.
+* `record_and_reraise_exception!(ex,attributes=nil)` - Record an exception and raise it.
+
+Suppose you want to instrument `RequireAuthBeforeHook` from the [hooks](/hooks) documentation. Although
+the hook's `before` method is instrumented by Brut already, let's add some metadata to that span, and also
+add a span around the login check.
+
+```ruby {11-16,18,20,23-26}
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+    is_home_page       = request.path_info.match(/^\/?$/)
+    is_auth_route      = request.path_info.match?(/^\/auth\//)
+    is_brut_owned_path = env["brut.owned_path"]
+
+    requires_login = !is_home_page  &&
+                     !is_auth_route && 
+                     !is_brut_owned_path
+    Brut.container.instrumentation.add_attributes(
+      requires_login:,
+      is_home_page:,
+      is_auth_route:,
+      is_brut_owned_path:
+    )
+
+    Brut.container.instrumentation.span("login-check") do |span|
+      if session.logged_in?
+        span.add_attributes(logged_in: true)
+        request_context[:authenticated_account] = session.authenticated_account
+        requires_login = false
+      else
+        span.add_attributes(logged_in: false)
+      end
+    end
+
+    if requires_login
+      redirect_to(Auth::LoginPage)
+    else
+      continue
+    end
+
+  end
+end
+```
+
+Now, for every request someone makes to our app, we will see a span for the `RequireAuthBeforeHook`, and
+inside that span, we'll see the attributes we added as well as a sub-span representing the login check
+(which itself will have an attribute about the user's logged-in status).
+
+### Client-Side Observability
+
+
+The class `Brut::FrontEnd::Handlers::InstrumentationHandler` is set up to receive information from the
+client-side to provide insights about client-side behavior as part of a server-side request.  Brut
+attempts to join up any client-side instrumentation to the request that served it.
+
+It does this `Brut::FrontEnd::Components::Traceparent` component, which is included in your default layout
+when you created your Brut app.  This creates a `<meta>` tag containing standardized information used to
+connect the client-side behavior to the server-side request.
+
+The Brut custom element `<brut-tracing>` uses this information, along with statistics from the browser, to
+send a custom payload back to Brut at the route `/__brut/instrumentation`, which is handled by the
+aforementioned `InstrumentationHandler`.
+
+You should then see client-side tracing information as a sub-span of your HTTP request.  The information
+available depends on the browser, and some browsers don't send much.
+
+## Testing
+
+Generally you don't want to test instrumentation unless it's highly complex and critical to the app's
+ability to be maintained.  Ideally, your end-to-end tests will cover all the instrumentation code you
+write so you can be sure that none of that causes a problem.
+
+## Recommended Practices
+
+Entire books and conferences exist on how to properly instrument your app.  Our suggestion is to take what
+you have by default and add additional instrumentation only to solve specific problems or identify
+specific issues.
+
+## 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_
+
+Brut does not have plans to support non-OTel instrumentation, nor does it have plans to provide hooks to
+use proprietary formats.  This could change of course.
+
+The client-side portion of this is highly customized.  The Otel open source code for the client side is
+massive and hugely complex, so Brut decided to try to produce something simple and straightforward as a
+start. This can and will evolve over time.

data/brutrb.com/javascript.md

@@ -0,0 +1,122 @@
+# JavaScript
+
+Brut provides basic bundling using [esbuild](https://esbuild.github.io/).  Brut does not support nor prevent the
+use of any front-end framework.  Brut does, however, include [BrutJS](/brut-js), a lightweight library of HTML custom
+elements and utility code.  These elements can provide a fair bit of front-end functionality using progressive
+enhancement without the need for a framework.
+
+## Overview
+
+All your app's JavaScript lives in `app/src/front_end/js`, or in modules you bring in via `package.json`.  Brut
+will *bundle* all of that up into a single `.js` file that is served up with your app.  Brut does this by using
+esbuild, a stable and standardized tool for bundling JavaScript.
+
+The way esbuild works is to be given an *entry point* that requires, or transitively requires, all of your
+JavaScript by using ES6 modules. `app/src/front_end/js/index.js` is the entry point for your app.
+
+For example, if you have a `Widget` class that uses a `Status` class, and you also use the third party library
+"foobar", here is how all the files would look.
+
+First, `package.json` (in your app's root) would include `"foobar"` (and it must set `"type"` to `"module"`):
+
+```json {2,5}
+{
+  "name": "your-app",
+  "type": "module",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "foobar": "^0.0.11"
+  },
+  "devDependencies": {
+    "chokidar-cli": "^3.0.0",
+    "esbuild": "^0.20.2",
+    "jsdom": "^25.0.1",
+    "mocha": "^10.7.3",
+    "playwright": "^1.50.1"
+  },
+}
+```
+
+Next, `app/src/front_end/js/index.js` would import both `"foobar"` and `"Widget"`:
+
+```javascript
+import { foobar } from "foobar"
+import Widget from "./Widget"
+
+// ...
+```
+
+Notice that "foobar", since it's brought in as a third party dependency, is imported without a `./`.  Be careful
+here!  Every third party library has a different syntax for how to import whatever it is or does. Consult the
+documentation of each third party library you wish to import.
+
+The second `import` uses a `./` because it's importing a file in `app/src/front_end/js` namely `Widget.js`.  Be
+careful here, too, as you must be sure to `export` the right thing.  Here's what `app/src/front_end/js/Widget.js`
+might look like:
+
+```javascript
+import Status from "./extra/Status"
+
+class Widget {
+  status = new Status()
+}
+
+export default Widget
+```
+
+Note that we import `Status` here.  Unlike Ruby, ES6 modules requires each class that references a class to
+import it explicitly.  Also notice that we do `export default Widget`, which allows `import Widget` to work.
+
+Finally, `app/src/front_end/extra/Status.js` looks like so:
+
+```javascript
+class Status {
+}
+export default Status
+```
+
+When `bin/build-assets` runs, esbuild will use `app/src/front_end/js/index.js` as its *entry point*, and will
+bundle both `Widget.js` and the "foobar" library.  When it bundles `Widget.js`, it will see that it imports
+`extra/Status.js` and bundle that, too.
+
+This bundle can be included in your app by ensuring this is in your layout:
+
+```ruby {5}
+def view_template
+  doctype
+  html(lang: "en") do
+    head do
+      script(defer: true, src: asset_path("/js/app.js"))
+      # ...
+```
+
+The `asset_path` helper takes a logical path—`/js/app.js`—and returns the actual path the browser can use.  More
+details on this can be found in [assets](/assets).
+
+## Testing
+
+Client-side behavior is best tested with end-to-end tests, however you can simplify your end-to-end tests by
+creating unit tests of your custom elements.  BrutJS provides support for this. TBD LINK.
+
+## Recommended Practices
+
+Brut encourages you to use HTML custom elements as progressive enhancements over server-generated views.  This
+sort of client-side code will age well.  The toolchain and dependencies are minimal, so you will not have to
+worry too much about code written this way.
+
+It *will* be lower level and more verbose than existing frameworks.  We would argue that it is not significantly
+more difficult and the sustainability is worth it.
+
+## 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_
+
+Currently, Brut only supports a single entry point and bundle.  This could be easily made more flexible if there
+is a desire to finely tweak the JavaScript loaded on specific pages.
+
+Brut also does not expose any esbuild configuration.  This could be provided in the future, but for now, it is
+hard-coded.

data/brutrb.com/jobs.md

@@ -0,0 +1,14 @@
+# Background Jobs
+
+Brut provides little direct support for background jobs. Currently, Brut recommends Sidekiq, since it is
+battle-tested, well-supported, and open source.
+
+When you set up your Brut app, it should ask if you want Sidekiq support and add the necessary configuraiton.
+
+It will expect jobs in `app/src/back_end/jobs`.
+
+> [!WARNING]
+> The way Sidekiq is configured with Brut is effective and reliable, but it is complex.  It currently
+> involves several moving parts to make it work properly.  This will be an area for improvement.
+
+