brut 0.10.0 → 0.12.0

data/brut-js/package.json

@@ -1,8 +1,11 @@
 {
   "name": "brut-js",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
-  "keywords": [ "WebComponents", "Custom Elements" ],
+  "keywords": [
+    "WebComponents",
+    "Custom Elements"
+  ],
   "bugs": {
     "url": "https://github.com/thirdtank/brut-js/issues",
     "email": "davec@naildrivin5.com"
@@ -25,7 +28,7 @@
     "bundle": "esbuild --sourcemap --bundle src/appForTestingOnly.js --outfile=specs/public/js/bundle.js"
   },
   "devDependencies": {
-    "esbuild": "^0.24.0",
+    "esbuild": "^0.24.2",
     "jsdom": "^25.0.1",
     "mocha": "^10.8.2"
   }

data/brut-js/specs/AjaxSubmit.spec.js

@@ -6,7 +6,7 @@ describe("<brut-ajax-submit>", () => {
       <input required type="text" name="some-text">
       <input required type="number" name="some-number">
       <brut-ajax-submit submitted-lifetime="10">
-        <button>Submit</button>
+        <button name="button-name" value="button-value">Submit</button>
       </brut-ajax-submit>
     </form>
   `).onFetch( "/foo", [
@@ -43,12 +43,13 @@ describe("<brut-ajax-submit>", () => {
       assert.equal(detailReceived.body.innerHTML,"<div>some html</div>")
       assert(element.getAttribute("requesting") == null)
       assert(element.getAttribute("submitted") != null)
-      waitForSetTimeout(11).then( () => {
+      return waitForSetTimeout(11).then( () => {
         assert(element.getAttribute("submitted") == null)
         return readRequestBodyIntoString(fetchRequests[0]).then( (string) => {
           const params = new URLSearchParams(string)
           assert.equal(params.get("some-text"),"Some Text")
           assert.equal(params.get("some-number"),"11")
+          assert.equal(params.get("button-name"),"button-value")
         })
       })
 
@@ -79,7 +80,7 @@ describe("<brut-ajax-submit>", () => {
       <input required type="text" name="some-text">
       <input required type="number" name="some-number">
       <brut-ajax-submit submitted-lifetime="10">
-        <button>Submit</button>
+        <button name="button-name" value="button-value">Submit</button>
       </brut-ajax-submit>
     </form>
   `).onFetch( "/foo", [
@@ -114,6 +115,7 @@ describe("<brut-ajax-submit>", () => {
           const params = new URLSearchParams(string)
           assert.equal(params.get("some-text"),"Some Text")
           assert.equal(params.get("some-number"),"11")
+          assert.equal(params.get("button-name"),"button-value")
         })
       })
     })
@@ -123,7 +125,7 @@ describe("<brut-ajax-submit>", () => {
       <input required type="text" name="some-text">
       <input required type="number" name="some-number">
       <brut-ajax-submit submitted-lifetime="10" max-retry-attempts=2>
-        <button>Submit</button>
+        <button name="button-name" value="button-value">Submit</button>
       </brut-ajax-submit>
     </form>
   `).onFetch( "/foo", [
@@ -183,7 +185,7 @@ describe("<brut-ajax-submit>", () => {
       </brut-cv-messages>
 
       <brut-ajax-submit submitted-lifetime="10">
-        <button>Submit</button>
+        <button name="button-name" value="button-value">Submit</button>
       </brut-ajax-submit>
     </form>
   `).onFetch( "/foo", [
@@ -283,7 +285,7 @@ Error that should be ignored
       </brut-cv-messages>
 
       <brut-ajax-submit submitted-lifetime="10" no-server-side-error-parsing>
-        <button>Submit</button>
+        <button name="button-name" value="button-value">Submit</button>
       </brut-ajax-submit>
     </form>
   `).onFetch( "/foo", [
@@ -346,4 +348,58 @@ Error that should be ignored
       })
     })
   })
+  withHTML(`
+    <form action="http://example.net/foo" method="POST">
+      <input required type="text" name="some-text">
+      <input required type="number" name="some-number">
+      <brut-ajax-submit submitted-lifetime="10">
+        <input type="submit" name="button-name" value="button-value">
+      </brut-ajax-submit>
+    </form>
+  `).onFetch( "/foo", [
+    { then: { status: 200, text: "<div>some html</div>" }},
+  ]
+  ).test("submits the form, when wrapped around an input type=submi, setting various attributes during the lifecycle", 
+         ({document,assert,fetchRequests,waitForSetTimeout,readRequestBodyIntoString}) => {
+
+    const element = document.querySelector("brut-ajax-submit")
+    const button  = element.querySelector("input[type=submit]") 
+    const text    = document.querySelector("input[name=some-text]")
+    const number  = document.querySelector("input[name=some-number]")
+
+    let okReceived = false
+    let detailReceived = null
+    element.addEventListener("brut:submitok", (event) => {
+      okReceived = true
+      detailReceived = event.detail
+    })
+
+    text.value   = "Some Text"
+    number.value = "11"
+
+    button.click()
+    assert(element.getAttribute("requesting") != null)
+
+    const promises = fetchRequests.
+      filter( (fetchRequest) => fetchRequest.promiseReturned ).
+      map( (fetchRequest) => fetchRequest.promiseReturned )
+
+    return Promise.all(promises).then( () => {
+      assert(okReceived)
+      assert(detailReceived)
+      assert.equal(detailReceived.body.innerHTML,"<div>some html</div>")
+      assert(element.getAttribute("requesting") == null)
+      assert(element.getAttribute("submitted") != null)
+      return waitForSetTimeout(11).then( () => {
+        assert(element.getAttribute("submitted") == null)
+        return readRequestBodyIntoString(fetchRequests[0]).then( (string) => {
+          const params = new URLSearchParams(string)
+          assert.equal(params.get("some-text"),"Some Text")
+          assert.equal(params.get("some-number"),"11")
+          assert.equal(params.get("button-name"),"button-value")
+        })
+      })
+
+    })
+  })
 })

data/brut-js/src/AjaxSubmit.js

@@ -10,6 +10,8 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  * 1. When the button is clicked, the form's validity is checked. If it's not valid, nothing happens.
  * 2. If the form is valid, this element will be given the `requesting` attribute.
  * 3. The request will be initiated, set to abort after `request-timeout` ms (see below).
+ *    The data submitted will be the contents of `new FormData(form)`, along with the 
+ *    name/value of the button that was clicked, if it has a name and value.
  * 4. If the request returns OK:
  *    - `requesting` will be removed and `submitted` will be added.
  *    - `submitted` will be removed after `submitted-lifetime` ms.
@@ -67,13 +69,21 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  *
  * @example
  * <form action="/widgets" method="post">
- *   <input type=text name=name>
+ *   <input type="text" name="name">
  *
  *   <brut-ajax-submit>
- *     <button>Save</button>
+ *     <button name="button" value="save">Save</button>
+*    </brut-ajax-submit>
+ *   <brut-ajax-submit>
+ *     <button name="button" value="analyze">Analyze</button>
 *    </brut-ajax-submit>
  * </form>
  *
+ * <!-- When "Save" is clicked, "name" will have the value from the text field,
+ *      and "button" will have the value "save".
+ *      When "Analyze" is clicked, "name" will have the value from the text
+ *      field, and "button" will have the value "analyze". -->
+ *
  * @customelement brut-ajax-submit
  */
 class AjaxSubmit extends BaseCustomElement {
@@ -179,17 +189,20 @@ class AjaxSubmit extends BaseCustomElement {
     if (submitter == this.#button()) {
       event.preventDefault()
       const now = Date.now()
-      this.#submitForm(event.target, now, 0)
+      this.#submitForm(event.target, event.submitter, now, 0)
     }
   }
 
-  #submitForm(form, firstSubmittedAt, numAttempts) {
+  #submitForm(form, submitter, firstSubmittedAt, numAttempts) {
 
     const headers = new Headers()
     headers.append("X-Requested-With","XMLHttpRequest")
     headers.append("Content-Type","application/x-www-form-urlencoded")
 
     const formData = new FormData(form)
+    if (submitter && submitter.name) {
+      formData.append(submitter.name, submitter.value)
+    }
     const urlSearchParams = new URLSearchParams(formData)
 
     const timeoutSignal = AbortSignal.timeout(this.#requestTimeout)
@@ -251,7 +264,7 @@ class AjaxSubmit extends BaseCustomElement {
         }
         if (retry) {
           this.#requestErrorLogger("Trying again (attempt %d)",numAttempts +1)
-          setTimeout( () => this.#submitForm(form, firstSubmittedAt, numAttempts + 1), numAttempts * 10)
+          setTimeout( () => this.#submitForm(form, submitter, firstSubmittedAt, numAttempts + 1), numAttempts * 10)
         }
         else if (resubmit) {
           this.#requestErrorLogger("'retry' was marked false, but resubmit is 'true', so submitting through browser")
@@ -265,7 +278,14 @@ class AjaxSubmit extends BaseCustomElement {
     })
   }
 
-  #button = () => { return this.querySelector("button") }
+  #button = () => {
+    let button = this.querySelector("button")
+    if (!button) {
+      button = this.querySelector("input[type='submit']")
+    }
+    return button
+  }
+
 
   #submitFormThroughBrowser(form) {
     form.removeEventListener("submit",this.#formSubmitted)

data/brutrb.com/forms.md

@@ -83,6 +83,7 @@ for use in a radio button group. |
 |`Brut::FrontEnd::Components::SelectTagWithOptions` | Creates a `<select>` tag with
 `<option>` tags inside. |
 |`Brut::FrontEnd::Components::TextareaTag` | Creates a `<textarea>` tag. |
+|`Brut::FrontEnd::Components::ButtonTag` | Creates a `<button>` tag to submit the form. |
 
 All of these classes have an initializer that accepts:
 

data/brutrb.com/getting-started.md

@@ -9,6 +9,7 @@ The simplest way to use `mkbrut` is to use an existing [Docker image](https://hu
 
 ```
 docker run \
+       --pull always \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -u $(id -u):$(id -g) \
@@ -33,6 +34,7 @@ For now:
 
 ``` [Docker-based]
 docker run \
+       --pull always \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -u $(id -u):$(id -g) \
@@ -55,6 +57,7 @@ To create your app without the demo components:
 
 ``` [Docker-based]
 docker run \
+       --pull always \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -u $(id -u):$(id -g) \

data/brutrb.com/instrumentation.md

@@ -80,7 +80,99 @@ Here is a non-exhaustive list of what Brut automatically instruments:
 
 ### Adding Your Own Instrumentation
 
-You can add instrumentation in a few ways:
+You can add instrumentation in two main ways, both of which can be used together.
+
+#### Instrumenting Existing Methods
+
+Although Brut instruments the entrypoints to pages, handlers, and components, you will likely have your own set of back-end business logic that needs to be instrumented.  If you aren't trying to diagnose a specific problem and just want to see your back-end class' methods show up in your instrumentation vendor's dashboard, `Brut::Instrumentation::Methods` will be the easiest way to do that.
+
+`Brut::Instrumentation::Methods` can be included in any class, and provides three class methods, which are *mutually exclusive*:
+
+* `instrument_all` instruments all methods, public and private.
+* `instrument_public` instruments only public methods.
+* `instrument` instruments one or more named methods.
+
+`initialize` is never instrumented.
+
+Consider this class:
+
+```ruby
+class Widget
+  def initialize
+    # ...
+  end
+
+  def search
+    # ...
+  end
+
+  def save
+    # ...
+  end
+
+private
+
+  def delete_orphans
+    # ...
+  end
+end
+```
+
+If we use `instrument_all`…
+
+```ruby
+class Widget
+  include Brut::Instrumentation::Methods
+  instrument_all
+
+  # ...
+end
+```
+
+…`search`, `save`, and `delete_orphans` will be instrumented.  If we use `instrument_public`…
+
+```ruby
+class Widget
+  include Brut::Instrumentation::Methods
+  instrument_public
+
+  # ...
+end
+```
+
+…then only `search` and `save` are instrumented.
+
+We can pick and choose by using `instrument`.
+
+```ruby{2,7,20}
+class Widget
+  include Brut::Instrumentation::Methods
+  def initialize
+    # ...
+  end
+
+  instrument def search
+    # ...
+  end
+
+  def save
+    # ...
+  end
+
+private
+
+  def delete_orphans
+    # ...
+  end
+  instrument :delete_orphans
+end
+```
+
+Above, `search` and `delete_orphans` are instrumented. Since `def` in Ruby returns a symbol, `instrument def search` is the same as `instrument :search`.
+
+#### Explicit Instrumentation with Spans, Attributes, and Events
+
+To add explicit instrumentation, you'll create one or more of the following:
 
 * *Spans* record a block of code. They are shown as a sub-span if one is already in effect.  When you
 create a span, that means it will be shown in the context of the HTTP request.
@@ -164,6 +256,39 @@ aforementioned `InstrumentationHandler`.
 
 You should then see client-side tracing information as a sub-span of your HTTP request.  The information available depends on the browser, and some browsers don't send much. Also keep in mind that clock drift is real and while client-side timings are accurate, the timestamps will not be.
 
+### Logging
+
+Brut configures [SemanticLogger](https://logger.rocketjob.io/), but uses it sparingly.  Currently, Brut performs very little logging, and no request logging.  You may have noticed that your app doesn't produce a lot of output in development.  Brut's assumption is that you will use an OpenTelemetry vendor to understand your app in production or the otel-desktop-viewer in developoment.
+
+That said, since SemanticLogger is configured, you can use it at will:
+
+```ruby
+class HomePage
+  def page_template
+    SemanticLogger[self.class].debug "page being rendered"
+    
+    # ...
+
+  end
+end
+```
+
+The logging system is currently not very configurable, and works as follows:
+
+* In development, log messages are written to the standard output and to `logs/development.log`
+* In test, log messages are written to `logs/test.log`
+* In production, log messages are written to the standard output
+
+The default log level is "debug" for the web app at "fatal" for CLI apps.  You can set `LOG_LEVEL` in the environment to change this:
+
+* `"debug"` - Show all messages
+* `"info"` -  Show info and above (not debug messages)
+* `"warn"` -  Show warnings and above (not info, not debug)
+* `"error"` -  Show errors and fatals only
+* `"fatal"` -  Show fatals only
+
+Most CLIs also allow `--log-level` to accept one of these strings as wel ass `--verbose` to set the log level to debug.
+
 ## Testing
 
 Generally you don't want to test instrumentation unless it's highly complex and critical to the app's
@@ -182,11 +307,25 @@ specific issues.
 > Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
 > internals, the source code is always more correct.
 
-_Last Updated June 12, 2025_
+_Last Updated Aug 27, 2025_
+
+OpenTelemetry is notoriously opaque and, ironically, unobservable in its own behavior.  Thus, the implementation is subject to change as I figure out what actually does what.
 
+### Web Requests
 
-Brut does not have plans to support non-OTel instrumentation, nor does it have plans to provide hooks to use proprietary formats.
+`Brut::FrontEnd::Middlewares::OpenTelemetrySpan` is configured in `Brut::Framework::MCP` as the first middleware.  It sets up the outer span for all web requests.  Inside each request block (the code internal to Brut that calls handlers or pages), this span's name is modified with the HTTP method and path via the `brut.otel.root_span` in the Rack environment.
+
+### Client-Side
 
 The client-side portion of this is highly customized.  The Otel open source code for the client side is
 massive and hugely complex, so Brut decided to try to produce something simple and straightforward as a
 start. This can and will evolve over time.
+
+### CLI Commands
+
+Brut CLI commands are instrumented as well,
+in `Brut::CLI::App` in `execute!`, however the trace only begins if the underlying command is going to be executed. This may change.
+
+### Sidekiq Jobs
+
+Although Brut currently does not provide a default Sidekiq configuration, if you set up Sidekiq and include the `opentelemetry-instrumentation-sidekiq` gem in your app's `Gemfile`, you should see instrumentation of your Sidekiq jobs.  In practice, this default set up doesn't seem to work very well, so expect this to change for the better.

data/brutrb.com/recipes/authentication.md

@@ -42,6 +42,7 @@ We'll also create `app/src/back_end/data_models/db/account.rb`:
 
 ```ruby
 class DB::Account < AppDataModel
+  has_external_id :a3 # !IMPORTANT: Make sure this is unique amongst your DB models
 end
 ```