brut 0.0.20 → 0.0.22

data/docs/assets/database-schema.md.BUjR0VS1.js

@@ -0,0 +1,63 @@
+import{_ as a,c as s,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Database Schema / Migrations","description":"","frontmatter":{},"headers":[],"relativePath":"database-schema.md","filePath":"database-schema.md"}'),n={name:"database-schema.md"};function l(o,e,r,h,d,p){return i(),s("div",null,e[0]||(e[0]=[t(`<h1 id="database-schema-migrations" tabindex="-1">Database Schema / Migrations <a class="header-anchor" href="#database-schema-migrations" aria-label="Permalink to &quot;Database Schema / Migrations&quot;">​</a></h1><p>Brut provides access to the database via the <a href="https://sequel.jeremyevans.net/" target="_blank" rel="noreferrer">Sequel library</a>. Sequel is fully featured and provides a lot of ways of interacting with and managing your database. Brut includes several plugins and extensions to provide opinionated default behavior or additional features.</p><p>One thing to keep in mind is that Brut refers to your database layer as <em>database models</em> (notably not the un-qualified &quot;models&quot;). Brut treats this layer as a <em>model</em> of your database, not a model of your <em>domain</em> (though you are free to conflate the two).</p><p>This section details how to manage your database schema.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Brut currently only supports Postgres. Sequel supports many database systems, however Brut&#39;s extensions are currently geared toward Postgres only.</p></div><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Brut uses <em>migrations</em> to control and manage the schema of your database. Migrations are changes to the schema that depend on the changes before them. In a running production database, you will not be able to create the database schema from scratch—you will have to modify the existing schema to produce the schema you want.</p><p>For example, if you have a table <code>widgets</code> that has a <code>name</code> and <code>description</code>, to add a <code>status</code> field, you cannot <code>drop table widgets</code> and then <code>create table widgets(...)</code> with the fields. You must instead <code>alter table widgets(...)</code> to add the new column.</p><p>Thus, each migration file is a change to the schema produced by all previous migration files.</p><p>Brut&#39;s provides this via Sequels. See <a href="https://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html" target="_blank" rel="noreferrer">both</a> <a href="https://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html" target="_blank" rel="noreferrer">docs</a> for details on the API. Any schema modification method Sequel documents is available, however some default behavior has changed.</p><p>Schema files are located in <code>app/src/back_end/data_models/migrations</code> and are named using a timestamp-based scheme. This means that when you create a new migration, its name will be based on the time and date you created it, and any migrations that have not been applied will be applied in timestamp order.</p><h3 id="creating-migrations" tabindex="-1">Creating Migrations <a class="header-anchor" href="#creating-migrations" aria-label="Permalink to &quot;Creating Migrations&quot;">​</a></h3><p>To create a migration, use <code>bin/db new-migration</code>. It accepts any number of arguments that will be joined together to form the filename:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; bin/db new-migration user accounts</span></span>
+<span class="line"><span>[ bin/db ] Migration created:</span></span>
+<span class="line"><span>    app/src/back_end/data_models/migrations/20250508132646_user-accounts.rb</span></span></code></pre></div><p>The file is created mostly blank:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Sequel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">migration</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  up </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Sequels&#39; migration system is similar to Active Record&#39;s/Rails&#39; in design and spirit, but the API is different. Please consult the documentation and don&#39;t assume Active Record&#39;s DSL will work. It will not.</p><p>One thing to note is that Brut encourages the creation of only &quot;up&quot; migrations. That is, migrations that change a database. &quot;Down&quot; migrations, which revert a change, are discouraged. See <em>Recommended Practices</em> for a detailed explanation.</p><p>This is also why Sequel&#39;s <code>change</code> method is not included in the scaffolded code. <code>change</code>, like Active Record&#39;s method of the same name, automagically creates both &quot;up&quot; and &quot;down&quot; migrations, but <em>only</em> if you use the DSL. If you use raw SQL, <code>change</code> doesn&#39;t work. But that doesn&#39;t matter for Brut (again, see <em>Recommended Practices</em>).</p><p>Let&#39;s create a user accounts table that has an email field, a <code>deactivated_at</code> timestamp, and a <code>created_at</code> timestamp:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Sequel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">migration</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  up </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    create_table </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:accounts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      comment:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;People or systems who can access this system&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:text</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">unique:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:deactivated_at</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:timestamptz</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>A few notes that aren&#39;t obvious without knowing about Brut&#39;s extensions:</p><ul><li><code>comment:</code> is required. You must provide documentation about what table is for</li><li>The table has a primary key named <code>id</code> of type <code>int</code> that is a serial.</li><li><code>created_at</code> is created by default, with time <code>timestamptz</code> (AKA <code>timestamp with time zone</code>, see <a href="/space-time-continuum.html">Space/Time Continuum</a>).</li><li><code>email</code> is not null by default. <code>deactivated_at</code> <em>is</em> null because it&#39;s specified as such.</li></ul><p>To apply this migration use <code>bin/db migrate</code></p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; bin/db migrate</span></span></code></pre></div><p>If you create a new migration, it will use a timestamp that is alphanumerically greater than the one we just made and thus that migration will be applied after this one. Thus, you can rely on previous migrations having been applied when authoring new ones.</p><h3 id="managing-migrations" tabindex="-1">Managing Migrations <a class="header-anchor" href="#managing-migrations" aria-label="Permalink to &quot;Managing Migrations&quot;">​</a></h3><p>Sequel uses a special database table to understand which migrations have been run. This table will exist in production and prevent you from applying migrations twice or skipping a migration.</p><p>Note that managing a production database in this way requires knowledge of both your database system and the data itself. Brut can only provide so much to make this process manageable. You should consult <a href="https://github.com/ankane/strong_migrations?tab=readme-ov-file" target="_blank" rel="noreferrer">Strong Migrations&#39; README</a> and learn it deeply. Although it&#39;s targeted at Rails developers, the information here applies to any database management system.</p><h3 id="brut-extensions-and-changes-in-sequel-s-behavior" tabindex="-1">Brut Extensions and Changes in Sequel&#39;s Behavior <a class="header-anchor" href="#brut-extensions-and-changes-in-sequel-s-behavior" aria-label="Permalink to &quot;Brut Extensions and Changes in Sequel&#39;s Behavior&quot;">​</a></h3><p>Brut includes the following standard plugins and extensions:</p><ul><li><a href="https://sequel.jeremyevans.net/rdoc-plugins/files/lib/sequel/extensions/pg_array_rb.html" target="_blank" rel="noreferrer"><code>pg_array</code></a></li><li><a href="https://sequel.jeremyevans.net/rdoc-plugins/files/lib/sequel/extensions/pg_json_rb.html" target="_blank" rel="noreferrer"><code>pg_json</code></a></li><li><a href="https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/TableSelect.html" target="_blank" rel="noreferrer"><code>table_select</code></a>, which changes queries to prepend <code>*</code> with the table name, e.g. <code>select accounts.*</code> instead of <code>select *</code>.</li><li><a href="https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/SkipSavingColumns.html" target="_blank" rel="noreferrer"><code>skip_saving_columns</code></a> which will skip saving columns that the database generates.</li></ul><p>Brut also provides the following plugins and behavior changes:</p><ul><li><code>Sequel::Extensions::BrutInstrumentation</code>, which adds OpenTelemetry instrumentation to Sequel (see <a href="/instrumentation.html">Instrumentation</a>).</li><li><code>Sequel::Plugins::FindBang</code>, which adds <code>find!</code> to all models. This wraps Sequel&#39;s <code>first!</code> method, but provides a more helpful error message when no records are found</li><li><code>Sequel::Plugins::CreatedAt</code>, which automatically sets <code>created_at</code> when a record is created.</li><li><code>Sequel::Plugins::ExternalId</code>, which adds support for external IDs (see below)</li><li><code>Sequel::Extensions::BrutMigrations</code>, which enhances the migrations API (see below)</li></ul><h4 id="external-ids" tabindex="-1">External IDs <a class="header-anchor" href="#external-ids" aria-label="Permalink to &quot;External IDs&quot;">​</a></h4><p>It&#39;s often useful to provide a unique identifier for a record that is not the database primary key. There are many advantages to doing so, but the core value Brut has regarding this is that database primary and foreign keys are considered private and internal and for developer use only. It is trivial to produce externalizable keys, as you&#39;ll see, so there&#39;s no reason to expose primary keys.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Take care to differentiate the terms <em>primary key</em> and <em>key</em>. In relational database literature, and thus in Brut, a <em>key</em> is any value that uniquely identifies a record. <code>email</code> in the <code>accounts</code> table above is a key. The <em>primary key</em> is single source of truth for identifying records internally in the database. Thus, it can be used as a <em>foreign key</em> to create relationships between tables. Brut further implements this as a <em>surrogate</em> or <em>synthetic</em> key, which means the value itself has no business or domain meaning.</p></div><p>In Brut, an external ID is automatically generated by the database when a record is created. By convention, it is prefixed with a short string representing your app and a short string representing the table, followed by a unique hash.</p><p>For example, if our app&#39;s prefix is, say, &quot;my&quot; (for &quot;my app&quot;), and the accounts table&#39;s prefix is &quot;ac&quot; (for &quot;accounts&quot;), an external ID might look like <code>myac_3457238947239487</code>. This double-prefixing is extremely useful when sharing these values with the outside world. You can immediately identify an ID from your app <em>and</em> know what sort of thing it refers to.</p><p>To use external IDs in Brut, you must do three things:</p><ol><li><p>You must set your external ID prefix in <code>app/src/app.rb</code>. This should have been done when you created your Brut app, but it looks like so:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> App</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">App</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # ...</span></span>
+<span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">container</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">override</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;external_id_prefix&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div></li><li><p>When creating the table in a migration, use <code>external_id: true</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Sequel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">migration</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  up </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    create_table </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:accounts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      comment:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;People or systems who can access this system&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      external_id:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:text</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">unique:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:deactivated_at</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:timestamptz</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div></li><li><p>In your <a href="/database-access.html">data model class</a>, use <code>has_external_id</code> to specify the prefix for this table:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>class DB::Account &lt; AppDataModel</span></span>
+<span class="line"><span>  has_external_id :ac</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>  # ...</span></span>
+<span class="line"><span>end</span></span></code></pre></div></li></ol><p>Brut creates the external ID using Ruby code as part of Sequel&#39;s lifecycle hooks. It&#39;s only set a) on creation, and b) if there is no value provided when creating the record.</p><p>This means that you can set values explicitly if you like, <em>and</em> you can change them later. This is useful if you shared the value with someone you didn&#39;t mean to. Because these external IDs aren&#39;t use for referential integrity/foreign keys, they can be changed at any time, as long as the value is unique (which will be enforced by the database).</p><h3 id="brut-migration-changes-and-enhancement" tabindex="-1">Brut Migration Changes and Enhancement <a class="header-anchor" href="#brut-migration-changes-and-enhancement" aria-label="Permalink to &quot;Brut Migration Changes and Enhancement&quot;">​</a></h3><p>Brut attempts to set default behavior for migrations to encourage a modicum of best practices. This lists out the changes and a brief explanation for the purpose of the change.</p><ul><li><p><strong>Automatic synthetic primary key named <code>id</code> of type <code>int</code>.</strong> You almost always want this. You can change the primary key configuration per table if you like, but if you do nothing, you get a primary key that works for 99% of your needs.</p></li><li><p><strong>Automatic <code>created_at</code> of type <code>timestamptz</code>.</strong> It&#39;s a good practice to store the date a record was created. This can help with debugging and provide a reliable sort key for data that otherwise has none. It uses <code>timestamp with time zone</code>, which you are encouraged to use always. See <a href="/space-time-continuum.html">Space/Time Continuum</a> for details.</p></li><li><p><strong>No automatic <code>updated_at</code>.</strong> While you are free to add <code>updated_at</code>, in practice this column creates more problems than it solves. If you need to know when data has changed, it is almost always better to do this with an audit table, event log, or special-purpose field.</p></li><li><p><strong><code>create_table</code> requires <code>comment:</code>.</strong> Just document your tables. It takes two seconds and can save a lot of time later.</p></li><li><p><strong>Support for external IDs via <code>external_id:</code>.</strong> As discussed above, this will create a unique <code>external_id</code> column on your table and ensure it has a value on creation.</p></li><li><p><strong>Columns are <code>NOT NULL</code> by default.</strong> Null is not a valid value. In many cases, your columns should not allow <code>NULL</code> (<code>nil</code>), so in Brut apps, you must opt into nullable columns. You can use <code>null: true</code> to make a column nullable.</p></li><li><p><strong>Foreign keys are <code>NOT NULL</code> and have an index created for them by default.</strong> Foreign keys should rarely be <code>NULL</code> and you almost always want an index on them, since you are likely to using them in queries, e.g. <code>account.widgets</code> would join on <code>accounts.widget_id</code>. You can opt out of either via <code>null: true</code> and <code>index: false</code>.</p></li><li><p><strong>The method <code>key</code> allows you to specify a non-primary key, AKA a unique index</strong>. Suppose our <code>accounts</code> table allowed duplicate email addresses, but only one per <code>organization_id</code>. You&#39;d model this by creating a unique index on <code>(email,organization_id)</code>. In Brut:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Sequel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">migration</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  up </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    create_table </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:accounts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      comment:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;People or systems who can access this system&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      external_id:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:text</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">unique:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      foreign_key </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:organization_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:organizations</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:deactivated_at</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:timestamptz</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
+<span class="line"></span>
+<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      key [</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:organization_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>This allows your migrations to be more expressive <em>and</em> make it easier to set up unique constraints that relate to your business logic or domain.</p></li></ul><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Generally, you don&#39;t test database migrations, however you may want to test constraints or other logic you have set up. Techniques for doing this are in the <a href="/database-access.html#testing">database access</a> section.</p><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><h3 id="ephemeral-dev-database" tabindex="-1">Ephemeral Dev Database <a class="header-anchor" href="#ephemeral-dev-database" aria-label="Permalink to &quot;Ephemeral Dev Database&quot;">​</a></h3><p>Brut intends for your develompent database to be ephemeral. Your entire workflow should be built around it being OK and normal to completely blow away your development database and recreate it. This is why down migrations (and the use of <code>change</code>) are discouraged. You really don&#39;t need them.</p><p>Assuming you have <a href="/seed-data.html">seed data</a> set up properly, you can reliably reset everything like so:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; bin/db rebuild</span></span>
+<span class="line"><span>&gt; bin/db seed</span></span>
+<span class="line"><span>&gt; bin/db rebuild -e test</span></span></code></pre></div><p>As long as you don&#39;t change migrations that have been applied in production, you can safely run the above commands to iterate on a schema change.</p><p>This does imply that you should not run business logic or make <em>data</em> changes in your migration files. No migration should rely on specific data being in the database.</p><p>This workflow my be much different from what you are used to, but you will be quite happy when you adopt it. The days of downloading a carefully-curated database image and taking great care to never delete it are over.</p><h3 id="use-your-database-it-is-awesome" tabindex="-1">Use Your Database, It is Awesome <a class="header-anchor" href="#use-your-database-it-is-awesome" aria-label="Permalink to &quot;Use Your Database, It is Awesome&quot;">​</a></h3><p>Your database is the only part of the system that has any chance of ensuring data integrity. You can use constraints, types, foreign keys, etc. to ensure that the data in your database is correct, based on your current understandings. Code-based validation systems <strong>cannot achieve this on any level</strong>.</p><p>Thus, you are encouraged to learn about your database&#39;s features and use them!</p><p>For example, here&#39;s a way to add full text search to an existing table in Postgres:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">add_column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:full_text_search</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  :tsvector</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  generated_always_as:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Sequel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">%{</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    (</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      setweight(to_tsvector(&#39;english&#39;, name),&#39;A&#39;) ||</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      setweight(to_tsvector(&#39;english&#39;, coalesce(description,&#39;&#39;)),&#39;B&#39;)</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    )</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  }</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  generated_type:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :stored</span></span></code></pre></div><p>If you are using Postgtes, why <em>not</em> use its features? Unless your app is database-agnostic, you should be using the features of your database, even if they aren&#39;t explicitly exposed via Sequel&#39;s Ruby API (that&#39;s why <code>Sequel.lit</code> exists).</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 8, 2025</em></p><p>As mentioned, Brut uses Sequel under the covers. This is unlikely to change.</p><p>As also mentioned, Brut&#39;s extensions often rely on Postgres. While we can all dream of a world where every developer uses the same database server, we don&#39;t live in that world. Brut should, some day, support all the databases that Sequel supports. For now, however, it only supports Postgres.</p><p>This hard-coded support is due to:</p><ul><li><code>pg_array</code></li><li><code>pg_json</code></li><li>Reliance on <code>citext</code> and <code>comment</code></li><li>Reliance on <code>timestamptz</code></li></ul><p>Brut is likely to add more Postgres-specific features before adding support for other databases.</p>`,70)]))}const k=a(n,[["render",l]]);export{u as __pageData,k as default};

data/docs/assets/database-schema.md.BUjR0VS1.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as s,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Database Schema / Migrations","description":"","frontmatter":{},"headers":[],"relativePath":"database-schema.md","filePath":"database-schema.md"}'),n={name:"database-schema.md"};function l(o,e,r,h,d,p){return i(),s("div",null,e[0]||(e[0]=[t("",70)]))}const k=a(n,[["render",l]]);export{u as __pageData,k as default};

data/docs/assets/deployment.md.Dbka4OTr.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Deployment","description":"","frontmatter":{},"headers":[],"relativePath":"deployment.md","filePath":"deployment.md"}'),n={name:"deployment.md"};function s(r,e,l,d,c,p){return a(),o("div",null,e[0]||(e[0]=[i('<h1 id="deployment" tabindex="-1">Deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;Deployment&quot;">​</a></h1><p>Brut apps are Rack apps, so they can be deployed in conventional ways. Brut apps are 12-factor apps and the scripts used for development are inteded to work for production as well.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Everyone deploys apps in different ways. Brut can&#39;t provide a simple solution for all deployment setups, so this document will outline considerations when setting up deployment.</p><p>The most direct way to understand what needs to happen is to look at <code>deploy/Dockerfile</code>, which is the foundation of a <code>Dockerfile</code> you can use. In particular, it shows you the commands needed to setup and run the app in production:</p><p>Beyond installing system software to run any Ruby web app, as well as whatever is needed for NodeJS and Postgres, the Brut-specific parts look like so:</p><ol><li>Install Ruby Gems with <code>bundle install</code></li><li>Install Node modules with <code>npm clean-install</code></li><li>Build all assets with <code>bin/build-assets</code> (this will bundle all CSS and Javascript, plus copy over any other <a href="/assets.html">assets</a> to the locations from where the Brut app will serve them)</li><li>Run the app with <code>bin/run</code></li></ol><p>Your Brut app also includes <code>bin/release</code> which is a script intended to run in the production environment after the code has been deployed, but before the app starts up. By default, it applies any needed migrations to the database.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>If you are using Docker, you can create the <code>Dockerfile</code>s and run them locally to see how they work. You will need to have local versions of all infrastructure (database, Redis, etc.), but if these work locally, there is a high chance they work in production.</p><p>If you are not using Docker, you will need to apply various techniques that are beyond the scope of this documentation.</p><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>Brut goes to great lengths to avoid environment-specific code. Much of Brut&#39;s behavior works the same in dev as it does in production. For example, assets are hashed in all environments.</p><p>Assuming your code does the same thing, there should be a minium of surprises. That all being said, here are some recommendations:</p><ul><li>Create a way to interact with external services in a testing capacity. For example, ensure you have a test user with a known email address and trigger an email to them. Or a company credit card you charge and refund.</li><li>Configure observability so you know what your app is doing at all times.</li><li>Configure a URL that, when accessed, produces an error. This allows you to check your error reporting system.</li><li>Create a page somewhere that shows the git SHA of your deployment, or some other unique, unambiguous version number. This will clarify what version of the code is actually running.</li></ul>',15)]))}const m=t(n,[["render",s]]);export{u as __pageData,m as default};

data/docs/assets/deployment.md.Dbka4OTr.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Deployment","description":"","frontmatter":{},"headers":[],"relativePath":"deployment.md","filePath":"deployment.md"}'),n={name:"deployment.md"};function s(r,e,l,d,c,p){return a(),o("div",null,e[0]||(e[0]=[i("",15)]))}const m=t(n,[["render",s]]);export{u as __pageData,m as default};

data/docs/assets/dev-environment.md.BNc8AYiK.js

@@ -0,0 +1,11 @@
+import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.1L-BeKqY.js";const o="/assets/dev-env-overview.Gj7NWM8-.png",n="/assets/dev-env-protocol.DysDAtnz.png",d="/assets/workspace-protocol.C0gXsoDb.png",g=JSON.parse('{"title":"Dev Environment","description":"","frontmatter":{},"headers":[],"relativePath":"dev-environment.md","filePath":"dev-environment.md"}'),r={name:"dev-environment.md"};function l(c,e,p,h,u,m){return s(),a("div",null,e[0]||(e[0]=[i('<h1 id="dev-environment" tabindex="-1">Dev Environment <a class="header-anchor" href="#dev-environment" aria-label="Permalink to &quot;Dev Environment&quot;">​</a></h1><p>Brut provides sophisticatd tooling to manage your dev environment</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>A development environments or <em>dev environment</em> is made up of two parts:</p><ul><li><em>Foundational Core</em> - the operating system and tools needed to run the app and <em>its</em> tools. This includes language runtimes, system libraries (like ImageMagick), and system tools like web browsers.</li><li><em>Workspace</em> - the tools and code bundled with the app that you use day-to-day to work on the app itself. This would include scripts to run the app in development, run tests, perform scaffolding, or manage the database.</li></ul><p>On many teams, the Foundational Core is different per developer, since some run Linux, some run MacOs. Some might use mise to manage their version of Ruby while others use rbenv. Some will set up Postgres via homebrew, while others might use Popstgres.app.</p><p>Brut takes a different approach. Everyone shares the same Foundational Core, and this is defined by a <code>Dockerfile</code>, a <code>docker-compose.yml</code> file, and some lightweight Bash scripts.</p><p>This means that everyone uses the same version of everything, and they are all managed the same way.</p><p>Brut also provides sophisticated tooling for the Workspace. Like Rails, Brut provides a command-line based flow that can be scripted into any editor. Unlike Rails, Brut&#39;s Workspace is comprised of separate command-line apps and not Rake tasks.</p><h3 id="conceptual-overview" tabindex="-1">Conceptual Overview <a class="header-anchor" href="#conceptual-overview" aria-label="Permalink to &quot;Conceptual Overview&quot;">​</a></h3><p>Your dev environment consists of a Docker container that has languages, an operating system, and other system components installed in it. It will have access to the files on your computer so that it can run your app. The app will be exposed so that a browser on your computer can access it. Postgres will be run as a separate Docker container available to the dev Docker container.</p><p>Your editor and version control system run on your computer.</p><p><img src="'+o+'" alt="Conceptual Overview"></p><h3 id="foundational-core-command-line-apps" tabindex="-1">Foundational Core Command Line Apps <a class="header-anchor" href="#foundational-core-command-line-apps" aria-label="Permalink to &quot;Foundational Core Command Line Apps&quot;">​</a></h3><p>These are the commands you will use to manage the <em>foundational core</em>, which is the Docker containers and their contents.</p><p>A few brief terminoloy notes if you aren&#39;t familiar with Docker:</p><ul><li>A Docker <em>container</em> is akin to a virtual machine. On Linux this isn&#39;t strictly true, but conceptually, you can think of this like a virtual computer.</li><li>A Docker <em>image</em> is what you use to start a container. This is akin to a disk image you might use to create a new computer or virtual machine.</li><li>A Dockerfile (often named <code>Dockerfile</code>) is a set of instructions to create an image.</li></ul><p>A few verbs to provide additional help:</p><ul><li>One <em>builds</em> a Docker image from a Dockerfile.</li><li>One <em>starts</em> a Docker container from an image.</li><li>One <em>stops</em> a Docker conatiner when it&#39;s no longer needed.</li></ul><table tabindex="0"><thead><tr><th>App</th><th>Purpose</th></tr></thead><tbody><tr><td><code>dx/build</code></td><td>Builds a Docker <em>image</em> from a <code>Dockerfile.dx</code></td></tr><tr><td><code>dx/start</code></td><td>Starts all Docker containers, including those for databases and caches</td></tr><tr><td><code>dx/stop</code></td><td>Stops all Docker containers</td></tr><tr><td><code>dx/exec</code></td><td>Execute a command inside a running Docker container</td></tr></tbody></table><p>The workflow for the foundational core is shown in this diagram.</p><p><img src="'+n+'" alt="Foundational Core Workflow"></p><p>In words:</p><ol><li>You build the images based on the latest instrutions via <code>dx/build</code>.</li><li>You start up the environment with <code>dx/start</code>.</li><li>You then use <code>dx/exec</code> to execute commands from the Workspace (see below).</li><li>When you are done working for the day, <code>dx/stop</code> shuts everything down.</li></ol><h3 id="workspace-command-line-apps" tabindex="-1">Workspace Command Line Apps <a class="header-anchor" href="#workspace-command-line-apps" aria-label="Permalink to &quot;Workspace Command Line Apps&quot;">​</a></h3><p>The workspace is where you&#39;ll run your day-to-day commands, such as running tests, starting the dev server, managing the database schema, etc.</p><p>Several of the commands accept or require subcommands. Each CLI app responds to <code>--help</code> and will show you full documentation about what the command and subcommands do.</p><table tabindex="0"><thead><tr><th>App</th><th>Subcommand</th><th>Descriptions</th></tr></thead><tbody><tr><td><code style="white-space:nowrap;">bin/ci</code></td><td>None</td><td>Runs all tests and security checks</td></tr><tr><td><code style="white-space:nowrap;">bin/console</code></td><td>None</td><td>Starts up a local IRB session with your app loaded</td></tr><tr><td><code style="white-space:nowrap;">bin/db</code></td><td></td><td>Tools for managing the database</td></tr><tr><td></td><td><code>create</code></td><td>Create the database if it does not exist</td></tr><tr><td></td><td><code>drop</code></td><td>Drop the database if it exists</td></tr><tr><td></td><td><code>migrate</code></td><td>Apply any outstanding migrations to the database</td></tr><tr><td></td><td><code>new_migration</code></td><td>Create a new migration file</td></tr><tr><td></td><td><code>rebuild</code></td><td>Drop, re-create, and run migrations, effecitvely rebuilding the entire database</td></tr><tr><td></td><td><code>seed</code></td><td>Load seed data into the database</td></tr><tr><td></td><td><code>status</code></td><td>Check the status of the database and migrations</td></tr><tr><td><code style="white-space:nowrap;">bin/dbconsole</code></td><td>None</td><td>Starts up a <code>psql</code> session to your database</td></tr><tr><td><code style="white-space:nowrap;">bin/dev</code></td><td>None</td><td>Starts the app in dev mode, rebuilding assets and reload as needed</td></tr><tr><td><code style="white-space:nowrap;">bin/setup</code></td><td>None</td><td>Install and setup all third party libraries and other configuration needed to use the app</td></tr><tr><td><code style="white-space:nowrap;">bin/scaffold</code></td><td></td><td>Generate Brut classes or files like database migrations or page classes</td></tr><tr><td></td><td><code>action</code></td><td>Create a handler for an action</td></tr><tr><td></td><td><code>component</code></td><td>Create a new component and associated test</td></tr><tr><td></td><td><code>custom_element_test</code></td><td>Create a test for a custom element in your app</td></tr><tr><td></td><td><code>form</code></td><td>Create a form and handler</td></tr><tr><td></td><td><code>page</code></td><td>Create a new page and associated test</td></tr><tr><td></td><td><code>test</code></td><td>Create the shell of a unit test based on an existing source file</td></tr><tr><td></td><td><code>test:e2e</code></td><td>Create the shell of an end-to-end test</td></tr><tr><td><code style="white-space:nowrap;">bin/test</code></td><td></td><td>Run tests</td></tr><tr><td></td><td><code>audit</code></td><td>Audits all of the app&#39;s classes to see if test files exist</td></tr><tr><td></td><td><code>e2e</code></td><td>Run e2e tests</td></tr><tr><td></td><td><code>js</code></td><td>Run JavaScript unit tests</td></tr><tr><td></td><td><code>run</code></td><td>Run non-e2e tests (default)</td></tr></tbody></table><p>The workflow for your Workspace is shown in this diagram</p><p><img src="'+d+`" alt="Workspace Workflow"></p><p>In words:</p><ol><li>You&#39;ll run <code>bin/setup</code> to get everything set up for working.</li><li>You&#39;ll start your dev server with <code>bin/dev</code>.</li><li>You&#39;ll write code, using tools like <code>bin/db</code> and <code>bin/scaffold</code> to assist.</li><li>Using <code>bin/test</code>, you can test any code you&#39;ve written a test for.</li><li>When you are at a stopping point, use <code>bin/ci</code> to test the entire app.</li></ol><h3 id="extending-and-enhancing" tabindex="-1">Extending and Enhancing <a class="header-anchor" href="#extending-and-enhancing" aria-label="Permalink to &quot;Extending and Enhancing&quot;">​</a></h3><p>TBD</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>There aren&#39;t tests for this code, because you are using all day every day. Brut&#39;s test suite will ensure that the versions of these command line apps provided when you set up your app are working.</p><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>While you are free to set up mise or rbenv or whatever to run all this on your computer, this way of working is currently not supported nor encouraged. For now, Brut will focus on the Docker-based approach.</p><p>You are encouraged to understand how it works, especially because the Docker skills you learn in doing so will help with production deployment and operations.</p><p>Beyond this, we recommend that you keep a few things in mind with respect to automation:</p><ul><li>The <em>Foundational Core</em> is bootstrapped in a degenerate environment without reliable tools beyond Bash. This is why it&#39;s almost entirely written in Bash, since it&#39;s available everywhere and relatively stable.</li><li>The <em>Workspace</em> <strong>can and should</strong> rely on the languages and third party modules that are part of your app. Just keep in mind that <code>bin/setup</code> can only rely on programming language runtimes and not any particular Ruby gem having been installed.</li></ul><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated June 12, 2025</em></p><p>Everything in <code>bin/</code> is intended to be a short shim that calls into classes managed either by Brut or by your app. For example, here is <code>bin/db</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#!/usr/bin/env ruby</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">require</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bundler&quot;</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Bundler</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">require</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">require</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;pathname&quot;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">require</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;brut/cli/apps/db&quot;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">exit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">CLI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">app</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">       Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">CLI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Apps</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DB</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">       project_root:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Pathname</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">($0).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">dirname</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> /</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;..&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">     )</span></span></code></pre></div><p>These files have a lot of duplication, but should be relatively stable.</p><p>This means that Brut-provided CLIs <em>will</em> be updated when you update Brut. Compare this to the files in <code>dx/</code> which are entire Bash scripts that will not be updated when Brut is updated.</p>`,48)]))}const y=t(r,[["render",l]]);export{g as __pageData,y as default};

data/docs/assets/dev-environment.md.BNc8AYiK.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.1L-BeKqY.js";const o="/assets/dev-env-overview.Gj7NWM8-.png",n="/assets/dev-env-protocol.DysDAtnz.png",d="/assets/workspace-protocol.C0gXsoDb.png",g=JSON.parse('{"title":"Dev Environment","description":"","frontmatter":{},"headers":[],"relativePath":"dev-environment.md","filePath":"dev-environment.md"}'),r={name:"dev-environment.md"};function l(c,e,p,h,u,m){return s(),a("div",null,e[0]||(e[0]=[i("",48)]))}const y=t(r,[["render",l]]);export{g as __pageData,y as default};

data/docs/assets/doc-conventions.md.DCfRXXi-.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse('{"title":"Documentation Conventions","description":"","frontmatter":{},"headers":[],"relativePath":"doc-conventions.md","filePath":"doc-conventions.md"}'),r={name:"doc-conventions.md"};function i(n,e,u,d,c,l){return s(),o("div",null,e[0]||(e[0]=[a('<h1 id="documentation-conventions" tabindex="-1">Documentation Conventions <a class="header-anchor" href="#documentation-conventions" aria-label="Permalink to &quot;Documentation Conventions&quot;">​</a></h1><h2 id="terminology" tabindex="-1">Terminology <a class="header-anchor" href="#terminology" aria-label="Permalink to &quot;Terminology&quot;">​</a></h2><p>Brut attempts to use existing terminology where possible, particularly where that technology applies to the web platform. For example, there is not a thing called &quot;CSS variables&quot;, rather the term is &quot;custom properties&quot;. HTML entities are <em>elements</em> or <em>tags</em> that have <em>attributes</em>. As another example, HTML doesn&#39;t have <em>validations</em>, rather it as <em>constraints</em>, which can be <em>violated</em>.</p><p>When speaking about Ruby, we prefer the term <em>initializer</em> over constructor, <em>parameters</em> over arguments, and <em>methods</em> over messages. We also prefer <em>tests</em> over specs, however test files <em>are</em> located in <code>specs/</code> and named <code>*.spec.rb</code> to be consistent with RSpec&#39;s nomenclature. We prefer <em>end-to-end</em> or <em>e2e</em> tests instead of browser tests or request specs.</p><p>Further, Brut doesn&#39;t render HTML, it <em>generates</em> it. The browser renders the HTML for the website&#39;s visitor.</p><p>Lastly, the documentation tries to talk about the person accessing a website as a &quot;vistor&quot; not a &quot;user&quot;. Though the &quot;user&quot; nomenclature is near-ossified in software development, we feel &quot;visitor&quot; is more apt.</p><h2 id="structure-of-these-documents" tabindex="-1">Structure of These Documents <a class="header-anchor" href="#structure-of-these-documents" aria-label="Permalink to &quot;Structure of These Documents&quot;">​</a></h2><p>Each page here documents on aspect of Brut, called a <em>module</em>, and these pages are organized along four sections:</p><ul><li><strong>Overview</strong> - provides detailed information on how this part of Brut works, with minimal examples to orient you to the terms and design of that module. Links to reference documentation are provided inline as needed.</li><li><strong>Testing</strong> - information about how to write tests for the code in this module. For example, in <a href="/pages.html">Pages</a>, we detail how you are intended to test page classes.</li><li><strong>Recommended Practices</strong> - this section outlines what we believe is the best way to use the module, along with justifications for the recommended approach. While you are free to ignore this advice, it&#39;s often useful to understand the intention of the authors.</li><li><strong>Technical Notes</strong> - where appropriate, technical details about how or why the module works the way it does are provided. This section should be marked with a date to allow you to understand the recency of the information. It may not always be up to date, but this can help further clarify what is happening under the covers and why.</li></ul><h2 id="names-of-the-library-and-associated-modules" tabindex="-1">Names of the Library and Associated Modules <a class="header-anchor" href="#names-of-the-library-and-associated-modules" aria-label="Permalink to &quot;Names of the Library and Associated Modules&quot;">​</a></h2><p>This framework is called &quot;Brut&quot; though may be called &quot;BrutRB&quot;. It lives at <code>brutrb.com</code>.</p><p>The JavaScript library is called &quot;BrutJS&quot;, but is <code>brut-js</code> in code or the filesystem. &quot;Brut-JS&quot; is wrong, as is <code>brut_js</code>.</p><p>The CSS library is called &quot;BrutCSS&quot;, but is <code>brut-css</code> in code or the filesystem. &quot;Brut-CSS&quot; is wrong, as is &quot;brut-css&quot;.</p><h2 id="on-using-vitepress" tabindex="-1">On Using VitePress <a class="header-anchor" href="#on-using-vitepress" aria-label="Permalink to &quot;On Using VitePress&quot;">​</a></h2><p>This site is built using <a href="https://vitepress.dev" target="_blank" rel="noreferrer">VitePress</a>, which is a client-side heavy framework. It kinda goes against the ethos of Brut, but it is allowing me to write documentation that looks decent and is mostly navigable. I would like to use a more accessible, customized system for documenting Brut, but for now, it&#39;s more important to get the documentation out. A better documentation experience is planned.</p>',15)]))}const p=t(r,[["render",i]]);export{m as __pageData,p as default};

data/docs/assets/doc-conventions.md.DCfRXXi-.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse('{"title":"Documentation Conventions","description":"","frontmatter":{},"headers":[],"relativePath":"doc-conventions.md","filePath":"doc-conventions.md"}'),r={name:"doc-conventions.md"};function i(n,e,u,d,c,l){return s(),o("div",null,e[0]||(e[0]=[a("",15)]))}const p=t(r,[["render",i]]);export{m as __pageData,p as default};

data/docs/assets/end-to-end-tests.md.yfQHC0b5.js

@@ -0,0 +1,26 @@
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"End to End Tests","description":"","frontmatter":{},"headers":[],"relativePath":"end-to-end-tests.md","filePath":"end-to-end-tests.md"}'),n={name:"end-to-end-tests.md"};function o(r,e,l,h,p,d){return a(),t("div",null,e[0]||(e[0]=[i(`<h1 id="end-to-end-tests" tabindex="-1">End to End Tests <a class="header-anchor" href="#end-to-end-tests" aria-label="Permalink to &quot;End to End Tests&quot;">​</a></h1><p>Is there a greater pain the world than an end-to-end test? Is there a more punishing API than trying to convince a browser to browse and use a website? Is there an answer for why the way we interact with browsers when writing code is 100% different than the we do when writing a test?</p><p>Brut cannot answer these things, but it does provide a way to write end-to-end tests with a browser, with a somewhat slightly reduced amount of pain.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Brut uses <a href="https://playwright.dev/" target="_blank" rel="noreferrer">Playwright</a> and the <a href="https://playwright-ruby-client.vercel.app/" target="_blank" rel="noreferrer">playwright-ruby-client</a> to allow you to write end-to-end tests that use a web browser. Brut sets up headless Chromium to do this.</p><p>You can run End-to-End (e2e) tests with <code>bin/test e2e</code>. You must use this to run individual tests as well, since this will ensure proper set up for the tests, which is more than is needed for a normal unit test.</p><h3 id="using-playwright" tabindex="-1">Using Playwright <a class="header-anchor" href="#using-playwright" aria-label="Permalink to &quot;Using Playwright&quot;">​</a></h3><p>At a high level, e2e tests look like normal RSpec tests:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">require</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;spec_helper&quot;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RSpec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">describe</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;logging into the website&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>The contents of your <code>it</code> blocks will use <code>playwright-ruby-client</code> to interact with the browser and make assertions. The value <code>page</code> is available to use this API.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">require</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;spec_helper&quot;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RSpec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">describe</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;logging into the website&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  it </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;shows an error when login is invalid&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goto</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">     = page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">locator</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;form input[type=&#39;email&#39;]&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    password</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  = page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">locator</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;form input[type=&#39;password&#39;]&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    button</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    = page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">locator</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;form button&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    email.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fill</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pat@example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    password.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fill</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;12345678&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    button.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">click</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    flash</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">locator</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;[role=&#39;alert&#39;]&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(flash).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">to</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> have_text</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;No email/password in our system&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p><code>playwright-ruby-client</code> provides excellent documentation on how it has adapter Playwright&#39;s API for use in Ruby.</p><h3 id="test-setup" tabindex="-1">Test Setup <a class="header-anchor" href="#test-setup" aria-label="Permalink to &quot;Test Setup&quot;">​</a></h3><p>Brut will run your app via <a href="/api/Brut/SpecSupport/E2ETestServer.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::E2ETestServer</code></a>. It will run it before the first e2e test, leave it running during the remainder of the test suite, then stop it. This means that database changes your test makes will persist across tests.</p><p>If you are using Sidekiq, Sidekiq will be set up like normal. Jobs queued will go to Redis, and those jobs will be processed by Sidekiq, just like in production. Thus, you should not assert things about specific jobs, but rather assert the effects those jobs will have. Redis is flushed between each test.</p><h3 id="test-helpers-and-configuration" tabindex="-1">Test Helpers and Configuration <a class="header-anchor" href="#test-helpers-and-configuration" aria-label="Permalink to &quot;Test Helpers and Configuration&quot;">​</a></h3><p>Inside your test, <code>t</code> is available to produce translations. You can also access all your page and handler classes, so you can (and should) use <code>.routing</code>, e.g. <code>DashboardPage.routing</code>, to generate or access routes for your app.</p><p>You can set <code>e2e_timeout</code> on any test to override the default amount of time Playwright will wait for a locator to locate an element. The default is 5 seconds. \`, to generate or access routes for your app. You can also configure behavior with environment variables:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>E2E_TIMEOUT_MS</code></td><td>5000</td><td>Number of milliseconds Playwright will wait for a locator to appear</td></tr><tr><td><code>E2E_SLOW_MO</code></td><td>0</td><td>Number of milliseconds Playwright will pause between operations. Useful to detect race conditions</td></tr><tr><td><code>E2E_RECORD_VIDEOS</code></td><td>unset</td><td>If set, videos of each test run are saved in <code>tmp/e2e-videos</code></td></tr></tbody></table><h3 id="quirks-of-playwright" tabindex="-1">Quirks of Playwright <a class="header-anchor" href="#quirks-of-playwright" aria-label="Permalink to &quot;Quirks of Playwright&quot;">​</a></h3><p>The Playwright JavaScript API is heavily asycnhronous, requiring liberal use of <code>await</code>. The <code>playwright-ruby-client</code> wrapper abstracts that so you can write more straightfoward code.</p><p>The main thing to be aware of is that locators that fail only fail when you attempt to assert something.</p><p>For example</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">button</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">locator</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;form button&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># suppose this button doesn&#39;t exist</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">button.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">click</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # This is where you&#39;ll see a failure</span></span></code></pre></div><p>This hidden asynchronous behavior also means that certain calls will wait a period of time for the element you are locating to appear. This is why the example test above works without having to explicitly wait for a page refresh. After <code>button.click</code>, presumably the back-end is contacted and the page is re-rendered with an error. As long as that happens within a second or so, the code will wait for an element matching <code>[role=&#39;alert&#39;]</code> to show up.</p><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>E2e tests are slow. They can also be flaky if you aren&#39;t careful in how you write them and how you author your HTML.</p><h3 id="test-major-flows-not-exhaustive-branches" tabindex="-1">Test Major Flows, Not Exhaustive Branches <a class="header-anchor" href="#test-major-flows-not-exhaustive-branches" aria-label="Permalink to &quot;Test Major Flows, Not Exhaustive Branches&quot;">​</a></h3><p>E2e tests give the most value when they assert that a sequence of actions the visitor takes result in what you expect—a &quot;major flow&quot;. Testing some error cases can be useful, but you should not use e2e tests to assert every single possible thing that could happen on a page.</p><p>In fact, your app might be better off leaving some behaviors better untested instead of tested by an e2e test. Use your judgement and be aware of the carrying cost of each e2e test.</p><h3 id="use-css-selectors" tabindex="-1">Use CSS Selectors <a class="header-anchor" href="#use-css-selectors" aria-label="Permalink to &quot;Use CSS Selectors&quot;">​</a></h3><p>The main Playwright documentation encourages you to locate elements by &quot;accessible names&quot; and other indirect ways of finding elements. In practice, this is error prone and tedious. Determining the accessible name of an element is not always easy.</p><p>We recommend you assess your app&#39;s accssibility in another way than trying to do it while performing end-to-end tests. Instead, locate elements with CSS selectors—this is what you&#39;d use to debug your app so it makes sense as a testing technique.</p><p>Insulating your end-to-end tests from markup changes does not produce significant savinsg and can make tests more difficult to write.</p><h3 id="testing-must-inform-your-html" tabindex="-1">Testing Must Inform your HTML <a class="header-anchor" href="#testing-must-inform-your-html" aria-label="Permalink to &quot;Testing Must Inform your HTML&quot;">​</a></h3><p>To allow CSS selectors to survive minor changes to a page, your HTML should be authored with testing in mind. In the example above, we locate the flash by looking for <code>[role=&#39;alert&#39;]</code>, since this is the most semantically correct way to mark up a flash message that contains an error.</p><p>ARIA roles that should be applied for accessibility purposes can be leveraged as locators, as can custom elements. Remember that any custom element is valid, even if it has no associated JavaScript. Custom elements are an excellent way to &quot;tag&quot; markup for use in tests or progressively-enhanced behavior.</p><p>CSS classes, on the other hand, are not a good candidate for identifying markup in a test. CSS classes exist to afford visual styling of elements and are the most likely to change as the app evolves. A better fallback if there is no other way to locate an element is to use <code>data-testid</code>. It makes itself painfully clear why it&#39;s there. Use this sparingly, but it&#39;s there if you need it.</p><h3 id="asserting-the-lack-of-content-basically-doesn-t-work" tabindex="-1">Asserting the Lack of Content Basically Doesn&#39;t Work <a class="header-anchor" href="#asserting-the-lack-of-content-basically-doesn-t-work" aria-label="Permalink to &quot;Asserting the Lack of Content Basically Doesn&#39;t Work&quot;">​</a></h3><p>To assert that some content or an element <strong>is not</strong> on the page requires locating it and waiting the timeout for that locate to fail. This sucks. Don&#39;t do it.</p><p>If you need to assert that something did not happen, you may want to design your page or app such that markup appears that indicates whatever it is didn&#39;t happen. This is not ideal, but a web page is a living thing that never stops changing, so your test can&#39;t just assume it&#39;s all synchronous.</p><h3 id="try-to-use-the-defaults-for-timeouts" tabindex="-1">Try to Use the Defaults for Timeouts <a class="header-anchor" href="#try-to-use-the-defaults-for-timeouts" aria-label="Permalink to &quot;Try to Use the Defaults for Timeouts&quot;">​</a></h3><p>Your app should not take 5 seconds to do anythning, especially not inside a test. You may need to bump up the timeout to figure out what&#39;s going wrong, or set <code>E2E_SLOW_MO</code> to watch a video test, but once you&#39;ve sorted out the issue, restore these to their defaults.</p><p>If you <em>must</em> set <code>e2e_timeout</code> as metadata on test, <strong>explain why</strong> and try removing it every so often to make sure it&#39;s still needed.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated June 13, 2025</em></p><p>The test server is run bin <code>bin/test-server</code>, which is why Sidekiq will be running when your app is running for an e2e test.</p>`,48)]))}const k=s(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/end-to-end-tests.md.yfQHC0b5.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"End to End Tests","description":"","frontmatter":{},"headers":[],"relativePath":"end-to-end-tests.md","filePath":"end-to-end-tests.md"}'),n={name:"end-to-end-tests.md"};function o(r,e,l,h,p,d){return a(),t("div",null,e[0]||(e[0]=[i("",48)]))}const k=s(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/flash-and-session.md.BXY8RvT0.js

@@ -0,0 +1,93 @@
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const g=JSON.parse('{"title":"Flash and Session","description":"","frontmatter":{},"headers":[],"relativePath":"flash-and-session.md","filePath":"flash-and-session.md"}'),h={name:"flash-and-session.md"};function t(l,s,p,k,r,d){return n(),a("div",null,s[0]||(s[0]=[e(`<h1 id="flash-and-session" tabindex="-1">Flash and Session <a class="header-anchor" href="#flash-and-session" aria-label="Permalink to &quot;Flash and Session&quot;">​</a></h1><p>Brut sessions are stored in cookies, encrypted to prevent tampering. The <em>flash</em>, which is a way to temporarily store small bits of information between page loads, is encoded in the session.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Unlike Rails, the session and flash are presented to you as objects, not Hashes. By declaring the <code>session:</code> parameter on an initializer, you&#39;ll be given the current session for the request as an <code>AppSession</code>, which inherits from <a href="/api/Brut/FrontEnd/Session.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Session</code></a>. Similarly, declaring <code>flash:</code>, you&#39;ll get a <a href="/api/Brut/FrontEnd/Flash.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Flash</code></a>.</p><p>The idea is to use Ruby&#39;s type system to describe what data is in the session and flash.</p><h3 id="session" tabindex="-1">Session <a class="header-anchor" href="#session" aria-label="Permalink to &quot;Session&quot;">​</a></h3><p>Brut&#39;s session is somewhat richer than you might get from other frameworks. In particular, the session can provide you:</p><ul><li>The current <a href="/api/Brut/I18n/HTTPAcceptLanguage.html" target="_self" rel="noopener" data-no-router><code>Brut::I18n::HTTPAcceptLanguage</code></a>, which is the visitor&#39;s locale. See <a href="/i18n.html">I18n</a> for how this works and how to use this value.</li><li>The timezone as provided by the browser.</li><li>An explicitly-set timezone that may or may not be what the browser provided. See <a href="/space-time-continuum.html">Space-Time Continuum</a> for more details.</li></ul><p>The session also handles serializing the flash to and from the browser&#39;s cookies and can store any arbitrary data you like via <code>[]</code>. You are encouraged to add methods to your app&#39;s <code>AppSession</code> to make it explicit what you are storing.</p><p>Let&#39;s see the <a href="/hooks.html">route hook</a> from the <a href="/pages.html">pages</a> section again.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p>This hook is not production-ready. It lacks certain error-handling situations and makes an assumption about how the session is managed. It&#39;s for demonstration only. The <a href="/hooks.html">route hooks</a> section has a more appropriate example.</p></div><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> RequireAuthBeforeHook</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RouteHook</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> before</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">request_context:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">current_user_id</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">      user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DB</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">User</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">find</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">id:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> user</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        request_context[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> user</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>When this hook executes, <code>session</code> will be an <code>AppSession</code>, serialized from the browser&#39;s cookies. Here&#39;s what that class might look like:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/support/app_session.rb</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppSession</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Session</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> login!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">current_user:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> current_user.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">id</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> logout!</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> logged_in?</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    !!</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">current_user_id</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> current_user_id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> self[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>The session is a rich object and not just a thin wrapper over a Hash. You could even have the session perform the lookup in the database:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/support/app_session.rb</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppSession</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Session</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> login!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">current_user:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> current_user.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">id</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> logout!</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> logged_in?</span></span>
+<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    !!</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">current_user</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> current_user</span></span>
+<span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    DB</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">User</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">find</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">id:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">])</span></span>
+<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Now, the hook could call <code>current_user</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> RequireAuthBeforeHook</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RouteHook</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> before</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">request_context:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">logged_in?</span></span>
+<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      request_context[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:current_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">current_user</span></span>
+<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Let&#39;s see <code>LoginHandler</code> from the <a href="/handlers.html">handlers</a> section, to see how to save the current user. Given what we&#39;ve learned, the declaration of the <code>session:</code> parameter to the initializer means the relevant instance of <code>AppSession</code> will be passed in.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/handlers/login_handler.rb</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> LoginHandler</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppHandler</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @form    </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @session </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> handle</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">@form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">constraint_violations?</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">      authorized_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">AuthorizedUser</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">login</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        email:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        password:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">password</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      )</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> authorized_user.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">nil?</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        @form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">server_side_constraint_violation</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          input_name:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          key:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :login_not_found</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        )</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      else</span></span>
+<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">login!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">current_user:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> authorized_user.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> @form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">constraint_violations?</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      LoginPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> @form)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    else</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      redirect_to</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DashboardPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">routing</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Brut will handle saving the updated values in the response so when, in this case, the <code>DashboardPage</code> is rendered, it can see which user is logged in.</p><h3 id="flash" tabindex="-1">Flash <a class="header-anchor" href="#flash" aria-label="Permalink to &quot;Flash&quot;">​</a></h3><p>By default, your app will use Brut&#39;s flash class, <a href="/api/Brut/FrontEnd/Flash.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Flash</code></a>. This is because you typically don&#39;t need to enhance the flash. Brut&#39;s flash has an &quot;alert&quot; and &quot;notice&quot;, and you can use them however you see fit. You can also set arbitrary messages in the flash via <code>[]</code>.</p><p>The contents of the flash only survive one request, so anything you set will be available in that session&#39;s next request, but not after that.</p><p>Note that the flash&#39;s alert and notice are intended to be I18n keys. You don&#39;t have to use them this way, but it is encouraged. If you pass an array into <code>alert=</code> or <code>notice=</code>, the elements will be joined to form an I18n key.</p><p>You can create your own subclass if you need a richer flash class than the one Brut provides.</p><p>First, create your class. It can be anywhere, but we recommend <code>app/src/front_end/support/app_flash.rb</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/support/app_flash.rb</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppFlash</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Flash</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # For example</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> debug=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(debug)</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    self</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:debug</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> debug</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> debug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> self[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:debug</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> debug?</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">self.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">debug</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Then, in your <code>App</code>, located in <code>app/src/app.rb</code>, use <code>Brut.container.override</code> to change the class used for the flash:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> App</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Framework</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">App</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">container</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">override</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;flash_class&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      AppFlash</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    )</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Brut&#39;s configuration system is discussed in more detail in <a href="/configuration.html">Configuration</a>.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Testing your session or flash classes may not be super valuable, however they are normal Ruby objects so you can test them in a conventional way. Both classes treat their internals as a Hash, so you can implement and assert via the <code>[]</code> and <code>[]=</code> methods.</p><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>While you can use both the flash and the session has a hash of whatever, your are encouraged to avoid this in your production code. Create well-defined attributes or methods to manipulate these objects using the language of your domain.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 7, 2025</em></p><p>The session is based on <a href="https://github.com/rack/rack-session" target="_blank" rel="noreferrer"><code>Rack::Session</code></a>, which is configured explicitly in your app&#39;s <code>config.ru</code>. (TBD: WHY?)</p><p>The session object itself is created on demand for any route hook that needs it. Since <a href="/api/Brut/FrontEnd/RouteHooks/SetupRequestContext.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHooks::SetupRequestContext</code></a> requires the session, the <a href="/api/Brut/FrontEnd/RequestContext.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RequestContext</code></a> is created here and given the session (and flash) that is used for subsequent hooks and HTML generation.</p><p>The flash is created largely on-demand and is a special hash serialized into the session. The hash contains the current age of the flash and then all the messages. This format could use improvement and may change. <a href="/api/Brut/FrontEnd/RouteHooks/AgeFlash.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHooks::AgeFlash</code></a> is a route hook that handles increasing the age of the flash, however the flash itself controls when to &quot;age out&quot; messages. None of this is currently configurable.</p>`,41)]))}const c=i(h,[["render",t]]);export{g as __pageData,c as default};

data/docs/assets/flash-and-session.md.BXY8RvT0.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const g=JSON.parse('{"title":"Flash and Session","description":"","frontmatter":{},"headers":[],"relativePath":"flash-and-session.md","filePath":"flash-and-session.md"}'),h={name:"flash-and-session.md"};function t(l,s,p,k,r,d){return n(),a("div",null,s[0]||(s[0]=[e("",41)]))}const c=i(h,[["render",t]]);export{g as __pageData,c as default};