After the early demise of my iPhone 13 mini, I started fresh and didn't reinstall my previous apps. So I decided to give Numbers a try. I exported the Google Sheet as an Excel file and had no trouble opening it on Mac, and saving it to iCloud. On phones, there's "Enter data using forms in Numbers on iPhone". Each column can be customized with a type so "cost" can be currency and show the numbers keyboard, and "type" can be a pop up menu with a set list of options. It even imported the pivot table properly!

Sharing is available through iCloud web, and has familiar permissions and options. I also like the option to share as PDF. With Shortcuts, I added a "Record Mazda" shortcut that uses the "Add 'Values' to 'Form' in '2014 Mazda6 Touring'" Numbers task, and saved this Shortcut to my homescreen with a red car icon.

Browsers have good support for playing audio, so the idea was to build a player out of HTML/CSS and load local audiobooks into it:

<!-- choose a local audiobook file -->
<input type="file" />

<!-- set the src to the contents of the audiobook -->
<audio id="player"></audio>

To remember playback position, I store them in the url document fragment. It's a janky workaround because iOS Safari doesn't persist access grants to files⁴, so if I navigate away from the page, I can select the audiobook again and skip to where I left off. A nice side effect is it also works with Safari Handoff to share the URL between devices.

Getting playback and position working was straightforward. The first challenge was getting metadata details from an m4b. I started with mp4box.js which gave me good results for general audio metadata like title, artist, cover art, but there are audiobook specific tags including chpl/tref/chap for chapter information. I ran parallel experiments with manual parsing the file bytes and mp4box across a handful of audiobooks. Sometimes that metadata is the beginning bytes of a file, and sometimes the end. Sometimes there would be number chapters, but the actual chapter names would be in a different part of the document within JSON. I'm wary of this code and additional edge cases, so I have it fail gracefully when parsing fails or metadata isn't available. If chapter information is available, it's easy to set the player to scrub to that position. The player also emits change events which are used to persist playback position.

I started with:

• Choose a monochrome color palette. Respect system light dark mode.
• Focus on legibility. Review for contrast.
• Optimize for mobile viewports.

From there, I spent most of my time removing elements and copy. I chose familiar icons and set defaults I prefer for rewind, playback speed, and sleep timer. I didn't build any UI to change these, they're variables if you'd like to customize it.

For the blank state icon, I chose "audiobook" by Ahmad Roaayala from Noun Project https://thenounproject.com/browse/icons/term/audiobook/ (CC BY 3.0).

I wish the Nokia 8110 4g aka "Banana phone" from the matrix worked in the US, but I decided to make this look nice on 240x320 viewports too. If you have a feature phone or a KaiOS device, I'd love to hear if this player works⁵.

I'm working through the animations.dev course. Nothing fancy here, but added a transform 97% and ease-out on the buttons. I can imagine some animations around the cover art or shrinking the player controls, but I think those may feel excessive, especially on smaller screens.

The MediaSession API makes it easy to preview what's playing from the lock screen.

I thought about creating a static site generator that would create the player html page based on the audiobooks in a directory. But decided against it because I already had my books in iCloud and didn't want to use the network needlessly.

I considered using Origin Private File System OPFS because it didn't need user permissions, but this basically imports it into browser storage. Since there's no guarantee around storage size, I abandoned this too. It might be feasible for desktop, but my iPhone 17e with 100GB of free space only showed 3GB of available web storage. Some of my audiobooks are over a GB.

This doesn't work on a folder of MP3's, I only tested on M4B's.

It'd be interesting to wrap this within a native shell for file system access. I didn't try oauth to Google Drive, but there's potential to connect to other cloud storage as well. It's all more than I need though.

• Claude Sonnet 4.6 through GitHub Copilot CLI and Visual Studio Code
• File System API
• FileList
• File
• audio tag
• Origin Private File System

# /etc/NetworkManager/conf.d/99-adtran-compat.conf
[connection]
ipv4.dhcp-client-id=none

I noticed that I wasn't able to connect to my main wifi teatime5. However, "teatime5 Guest" worked fine. Eventually I needed to be on the main network so I could print puppy coloring pages.

I messed eero's settings, but remembered my wifi router is bridged to my adtrans modem / router. The adtrans was responsible for DHCP leases. "teatime5 Guest" was a separate network created and managed by eero, which explained why dhcp worked there.

I installed dhcp-client and was able to manually get an ip with:

$ sudo dnf install dhcp-client

$ sudo dhclient -v enp12s0

Aside: I have 3 network interfaces on this laptop wlp61s0 wifi, enp0s31f6 ethernet, enp12s0 thunderbolt (display with ethernet on the back). ip link lists available interfaces. nmcli con also works, but doesn't list disconnected interfaces.

$ ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp0s31f6: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN mode DEFAULT group default qlen 1000
    link/ether e8:6a:64:2e:59:ee brd ff:ff:ff:ff:ff:ff
    altname enxe86a642e59ee
3: wlp61s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DORMANT group default qlen 1000
    link/ether da:e7:76:ef:96:ce brd ff:ff:ff:ff:ff:ff permaddr 48:a4:72:9a:f6:14
    altname wlx48a4729af614
6: enp12s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
    link/ether 3c:07:54:6f:15:85 brd ff:ff:ff:ff:ff:ff
    altname enx3c07546f1585

Configuring NetworkManager to use dhclient didn't work. Logs showed it couldn't find the client. It may need a separate plugin:

# /etc/NetworkManager/conf.d/99-adtran-compat.conf
[main]
dhcp=dclient

# journalctl -u NetworkManager -f
Mar 29 11:46:09 fedora NetworkManager[50641]: <warn>  [1774809969.9349] dhcp: init: DHCP client 'dhclient' not available

The hack fix was to configure the interfaces as link-only, and run a script after connections are established:

$ sudo touch /etc/NetworkManager/dispatcher.d/99-adtran-dhcp
$ sudo chmod 755 /etc/NetworkManager/dispatcher.d/99-adtran-dhcp

The script executes after connect:

#!/bin/bash
INTERFACE=$1
ACTION=$2

# wlp61s0: wireless interfaces
# enp0s31f6: ethernet
# enp12s0: thunderbolt display with ethernet
if [[ "$INTERFACE" =~ ^(wlp61s0|enp0s31f6|enp12s0)$ ]] && [[ "$ACTION" == "up" ]]; then
    # Release any old/stale leases first
    /usr/sbin/dhclient -v -r "$INTERFACE"
    
    # Request a new lease and log the results for debugging
    /usr/sbin/dhclient -v "$INTERFACE" > /tmp/adtran_dhcp.log 2>&1
fi

This worked, but it'll probably bite me on some upgrade. To stay close to distro defaults, I needed to figure out the difference between requests sent by the internal dhcp client and dhclient.

Let's compare them back to back. First, fedora's default that sends a device id

$ sudo tcpdump -i enp12s0 -vvvn port 67 or port 68
tcpdump: listening on enp12s0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
11:04:19.931750 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto UDP (17), length 310)
    0.0.0.0.bootpc > 255.255.255.255.bootps: [udp sum ok] BOOTP/DHCP, Request from 3c:07:54:6f:15:85, length 282, xid 0x5b52b4e2, secs 1, Flags [none] (0x0000)
          Client-Ethernet-Address 3c:07:54:6f:15:85
          Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Request
            Client-ID (61), length 7: ether 3c:07:54:6f:15:85
            Parameter-Request (55), length 17:
              Subnet-Mask (1), Time-Zone (2), Domain-Name-Server (6), Hostname (12)
              Domain-Name (15), MTU (26), BR (28), Classless-Static-Route (121)
              Default-Gateway (3), Static-Route (33), YD (40), YS (41)
              NTP (42), Unknown (119), Classless-Static-Route-Microsoft (249), Unknown (252)
              RP (17)
            MSZ (57), length 2: 576
            Requested-IP (50), length 4: 192.168.1.99
            END (255), length 0

What dhclient sends:

# in another terminal: sudo dhclient -v enp12s0
$ sudo tcpdump -i enp12s0 -vvvn port 67 or port 68
tcpdump: listening on enp12s0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
11:20:15.835147 IP (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
    0.0.0.0.bootpc > 255.255.255.255.bootps: [udp sum ok] BOOTP/DHCP, Request from 3c:07:54:6f:15:85, length 300, xid 0x39a01019, Flags [none] (0x0000)
          Client-Ethernet-Address 3c:07:54:6f:15:85
          Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Request
            Requested-IP (50), length 4: 192.168.1.99
            Parameter-Request (55), length 13:
              Subnet-Mask (1), BR (28), Time-Zone (2), Classless-Static-Route (121)
              Domain-Name (15), Domain-Name-Server (6), Hostname (12), YD (40)
              YS (41), NTP (42), MTU (26), Unknown (119)
              Default-Gateway (3)
            END (255), length 0
            PAD (0), length 0, occurs 35

The line that the adtrans router doesn't like:

Client-ID (61), length 7: ether 3c:07:54:6f:15:85

This can be removed with the config:

# /etc/NetworkManager/conf.d/99-adtran-compat.conf
[connection]
ipv4.dhcp-client-id=none

After restarting NetworkManager with the new config:

$ sudo tcpdump -i enp12s0 -vvvn port 67 or port 68
tcpdump: listening on enp12s0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
11:02:57.938169 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto UDP (17), length 301)
    0.0.0.0.bootpc > 255.255.255.255.bootps: [udp sum ok] BOOTP/DHCP, Request from 3c:07:54:6f:15:85, length 273, xid 0xa885726a, secs 1, Flags [none] (0x0000)
          Client-Ethernet-Address 3c:07:54:6f:15:85
          Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Request
            Parameter-Request (55), length 17:
              Subnet-Mask (1), Time-Zone (2), Domain-Name-Server (6), Hostname (12)
              Domain-Name (15), MTU (26), BR (28), Classless-Static-Route (121)
              Default-Gateway (3), Static-Route (33), YD (40), YS (41)
              NTP (42), Unknown (119), Classless-Static-Route-Microsoft (249), Unknown (252)
              RP (17)
            MSZ (57), length 2: 576
            Requested-IP (50), length 4: 192.168.1.99
            END (255), length 0

Success!

Another alternative I didn't try was to make eero the primary router and configure the adtrans in bridge mode. I currently have the latter port forward to my web/ssh server.

Other configs that I tried for reference:

[main]
dhcp=internal

[connection]
# don't send, this works
ipv4.dhcp-client-id=none

# send a leading 01, some enterprise routers like this?
#ipv4.dhcp-client-id=01:48:a4:72:9a:f6:14

# use 4 digits of mac address instead of device id
# use a stable mac instead of a randomized one
#ipv4.dhcp-client-id=mac
#ipv4.dhcp-iaid=mac
#wifi.cloned-mac-address=permanent
#ethernet.cloned-mac-address=permanent

Useful commands for debugging:

$ nmcli con  # same as nmcli connection show
$ nmcli con up|down teatime5

$ systemctl restart NetworkManager
$ journalctl -u NetworkManager

$ sudo tcpdump -i enp12s0 -vvvn port 67 or port 68

I test drove these techniques on the Holdings page. I needed these changes to be incremental and opt-in to avoid breaking other pages.

Up until I shipped dark mode, I used tailwind's color utilities. Tailwind does come with a dark:, but it was hard to reason about and I found myself repeating a lot of utilties with slight variations (border-pink-300, bg-pink-300) and needing to find-and-replace several things to try different colors.

/* before */
input:focus {
  @apply border-pink-300;      /* light mode */
  @apply dark:border-pink-900; /* dark mode */
}

This pushed me to add an abstraction for semantic colors on top of the primitive color definitions.

/* after */
:root {
  /* semantic colors */
  --color-highlight: oklch(var(--lch-pink));
  
  /* primitive colors */
  --lch-pink: ...; /* light mode default */
  @media (prefers-color-scheme: dark) {
    --lch-pink: ...;  /* redefine it to fit dark */
  }
}

input:focus {
  border: 1px solid var(--color-highlight);
}

Instead of describing a border color as light pink in light mode, and dark pink in dark mode, it's styled with a single semantic --color-highlight and allows --lch-pink to be redefined by dark mode.

Not every color needed a semantic name. The pattern I learned was to define raw color primitives as --lch-[color]-[lighter|light|dark|darker] and optionally add semantic named colors like --color-[semantic-name]. When applying colors in dark mode, redefine the raw --lch-* color vars while relying on semantic --color-* vars for styling.

One aha moment was realizing that the variables are resolved at render. Notice how --color-highlight: oklch(var(--lch-pink)) uses --lch-pink before it is defined. This works because when a input:focus selector matches an element, --lch-pink will resolve to a value based on light or dark mode. Trust that the variables will have a value defined at some point, whether it's a app wide value in :root, as a fallback, in a component or variant, or inline at the html itself. This also explains why application.html.erb can load all the stylesheets and not worry about the load order.

<%= stylesheet_link_tag :all %>

I started with inline svg icons because this allowed me to easily change their colors by defining their stroke color as currentColor.

/* easy to style svg icon colors */
<div style="color: red">
  <!-- icon inherits color -->
  <svg stroke="currentColor"></svg>
</div>

But this stops working if the svg is in an external file

/* currentColor ignored */
.icon--search {
  background-image: url("data:..."); /* inlined in css */
  background-image: url("plus.svg"); /* or external file */
}

The 37signals approach uses the svg as an image-mask over a background. The strokes of the icon form the visible parts of the mask, and the color from the image show through the mask.

.icon {
  background-color: currentColor;
  mask-image: var(--svg);
}

.icon--search {
  --svg: url("search.svg");
}

Aside: propshaft translates url("search.svg") to the digested file. Neat. Having cached digested icon files means sending fewer bytes inline with the response.

When icons were background images, I used relative positioning and padding to add a magnifying glass icon to a search input:

input[type=search] {
  --inline-space: 1ch;

  background-image: url("search.svg");
  background-position: center left var(--inline-space);
  background-repeat: no-repeat;
  
  /* space + icon + space before input content */
  padding-inline-start: calc(--icon-size + var(--inline-space) * 2);
}

I liked how this kept the html semantic without a wrapper element. But this meant a fixed icon for both light and dark mode, and prevented using css variables for customization. My first thought was using a ::before pseudo element to add the background image, but <input>s don't allow pseudo elements. So I experimented with a wrapper:

<style>
  .icon-wrapper {
    position: relative;
    
    & .icon {
      position: absolute;
      
      /* center vertically */
      top: 50%;
      transform: translate-y(-50%);
    }
    
    & input {
      padding-inline-start: calc(var(--icon-size) + 2ch);
    }
  }
</style>
<div class="icon-wrapper">
  <span class="icon icon--search"></span>
  <input type="search" />
</div>

This worked, but I didn't like how the input had to calculate the correct padding to know where it started. What I really wanted was to use flexbox and have the following:

+---+--------+
| o | xxxxxx |
+---+--------+
o = icon
x = input text
- = border

Then I could use gap for spacing and flexbox for alignment. I thought I could get clever with an input background image and a mask:

input[type=search] {
  background-image: linear-gradient(blue, red);
  background-position: left center;
  background-size: 1em 1em;
  
  mask-image:
    url("search.svg"),             /* mask 1: icon color */
    linear-gradient(black, black); /* mask 2: input text */
}

This kinda worked, but ends up masking out the border on the icon side:

    +--------+
  o | xxxxxx |
    +--------+
o = icon
x = input text
- = border

I messed with the mask-* properties, and while mask-origin sounded promising, it still ended up masking out the border. With border widths defined in variables and additional masks, this felt doable, but I stopped because it felt complex and brittle.

Studying campfire's inputs.css, their approach is to style the wrapper like an input, and hide an input's styling when it's within a wrapper. Input styling is defined by .input and a wrapper acting as an input is an .input--actor.

<div class="input input--actor" style="display: flex; gap: 1ch">
  <span class="icon icon--search"></span>
  <input type="search" class="input" />
</div>

The clever bits here were

1. adding input border, outlines, focus states on the wrapper with .input 2. using a child selector to clear the actual <input> styling with css vars

/* inputs.css */
.input {
  border: 1px solid var(--input-border-color, gray);
}

.input--actor {
  & .input {
    /* hide when inside a wrapper acting as an input */
    --input-border-color: transparent;
  }
}

Campfire wraps all of it's inputs with these classes, assuming input styling has been reset in base.css. But since I wanted to make incremental changes without breaking inputs on other pages, I didn't pull in their base.css. Even if I had, the base reset uses a :where selector with zero specificity that wouldn't override my input[type=search] styling. I was impressed that campfire's stylesheets are self-contained and could be added to my project without overriding my styles.

• Think decoratively. What variables and fallbacks do I need?
• Undo-ing styles is a smell that suggests a missing css variable.
• Zero specificity :where for reset and base styling
• Define and redefine colors based on light / dark mode like --lch-blue
• Define named semantic colors like --color-link that depend on varying lch variables

• Modern CSS patterns in Campfire
• Campfire
• Fizzy
• Propshaft #7: Add digest to valid urls in assets
• MDN: mask

A minimalist and lightweight starter kit that prioritizes semantic syntax, making every HTML element responsive and elegant by default. Write HTML, Add Pico CSS, and Voilà!

— picocss.com

I've used this project for prototyping and some personal projects I haven't published. It lets me start with something beautiful without the distraction of setting up a design system. Up till now, I've used it by referencing the full source via CDN, but I wanted to dig into its internals and learn how it works.

After installing npm, sass, and pico v2.1.1, I tested it with the default options:

// main.scss
@use pico;

Compiled with:

npx sass --load-path=node_modules/@picocss/pico/scss main.scss main.css

The primary way to customize pico is via CSS variables, but sass allows customization at the compilation step. This allows you to choose a theme color, compile without css classes, change the css variable prefix, and ignore modules to reduce bundle size.

The descriptive module names preview what they're used for. I wanted to see the size of each of the modules after compilation. I took the default options from the docs and disabled every module. Compiling that outputs no CSS selectors and a copyright comment on the top. This serves as the baseline size.

Next I prompted Claude Sonnet 4.6 with

1. Enable each module one at a time
2. run npx sass --load-path=node_modules/@picocss/pico/scss main.scss with-module-XX.css replacing XX with module name
3. diff with previous and get the character count
4. add a comment to final main.css with the difference in size and description of what the module does

The annotated listing is:

// main.scss
@use "pico" with (
  $theme-color: "yellow",
  $modules: (
    // Themes
    "themes/default": false,         // +8106 — breakpoints, responsive typography, and color palette

    // Layout
    "layout/document": false,       // +756  — html/body resets: box-sizing, scrollbar, font-size, line-height
    "layout/landmarks": false,      // +317  — semantic sectioning: header, main, footer, aside padding/margin
    "layout/container": false,      // +612  — .container max-width centering with responsive breakpoints
    "layout/section": false,        // +213  — section vertical padding and spacing
    "layout/grid": false,           // +454  — CSS grid helper: .grid equal-column responsive layout
    "layout/overflow-auto": false,  // +87   — overflow-auto wrapper for horizontal scroll

    // Content
    "content/link": false,          // +2144 — <a> color, underline, hover/focus styles incl. role=button
    "content/typography": false,    // +4742 — headings h1–h6, p, ul/ol/dl, blockquote, strong, em, mark, del
    "content/embedded": false,      // +441  — img, svg, video, canvas max-width and responsive sizing
    "content/button": false,        // +7304 — <button> and input[type=submit/reset/button] full styling
    "content/table": false,         // +1244 — <table>, thead, tbody, tfoot, tr, th, td, overflow-auto
    "content/code": false,          // +1603 — <code>, <pre>, <kbd>, <samp> monospace and block styles
    "content/figure": false,        // +195  — <figure> margin/padding and <figcaption> muted color
    "content/misc": false,          // +282  — <hr>, <abbr>, <dialog>, <template>, <details>/<summary>

    // Forms
    "forms/basics": true,          // +14186 — input, textarea, select, fieldset, label full form system
    "forms/checkbox-radio-switch": false, // +6240 — styled checkboxes, radio buttons, and toggle switches
    "forms/input-color": false,     // +373  — <input type=color> sizing and border styles
    "forms/input-date": false,      // +2221 — date/time/week/month input styles and calendar icon
    "forms/input-file": false,      // +896  — <input type=file> custom file picker button styles
    "forms/input-range": false,     // +3287 — <input type=range> track, thumb, and focus styles
    "forms/input-search": false,    // +1730 — <input type=search> clear button and search icon styles

    // Components
    "components/accordion": false,  // +3248 — <details>/<summary> accordion animation and chevron icon
    "components/card": false,       // +2105 — .card with padding, background, border-radius, shadow
    "components/dropdown": false,   // +7139 — <details role=list> dropdown menu with positioning and animation
    "components/group": false,      // +6565 — .group for inline button+input combos with joined borders
    "components/loading": false,    // +2559 — [aria-busy=true] spinning loader with CSS animation
    "components/modal": false,      // +3794 — <dialog> modal overlay, transitions, close button
    "components/nav": false,        // +2910 — <nav> with breadcrumb, pagination, and link list styles
    "components/progress": false,   // +1873 — <progress> bar with fill color and animation
    "components/tooltip": false,    // +5366 — [data-tooltip] attribute-based tooltip with arrow

    // Utilities
    "utilities/accessibility": false, // +459 — .visually-hidden / [hidden] and focus-visible helpers
    "utilities/reduce-motion": false  // +490 — prefers-reduced-motion: disables transitions and animations
  )
);

The docs mention a lightweight version without classes and uncommon components is about ~50% smaller. I compared the full with light and came up with:

$ wc -c full.css light.css 
 91913 full.css
 48315 light.css

Resets are grouped with their respective components. The document level resets are pretty minimal.

// scss/layout/_document.scss
@use "sass:map";
@use "../settings" as *;

@if map.get($modules, "layout/document") {
  /**
   * Document
   * Content-box & Responsive typography
   */

  // Reboot based on :
  // - normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css
  // - sanitize.css v13.0.0 | CC0 1.0 Universal | github.com/csstools/sanitize.css
  // ––––––––––––––––––––

  // 1. Add border box sizing in all browsers (opinionated)
  // 2. Backgrounds do not repeat by default (opinionated)
  *,
  *::before,
  *::after {
    box-sizing: border-box; // 1
    background-repeat: no-repeat; // 2
  }

  // 1. Add text decoration inheritance in all browsers (opinionated)
  // 2. Add vertical alignment inheritance in all browsers (opinionated)
  ::before,
  ::after {
    text-decoration: inherit; // 1
    vertical-align: inherit; // 2
  }

  // 1. Change the line height in all browsers (opinionated)
  // 2. Breaks words to prevent overflow in all browsers (opinionated)
  // 3. Use a 4-space tab width in all browsers (opinionated)
  // 4. Remove the grey highlight on links in iOS (opinionated)
  // 5. Prevent adjustments of font size after orientation changes in iOS
  :where(:root),
  :where(:host) {
    -webkit-tap-highlight-color: transparent; // 4
    -webkit-text-size-adjust: 100%; // 5
    text-size-adjust: 100%; // 5
    background-color: var(#{$css-var-prefix}background-color);
    color: var(#{$css-var-prefix}color);
    font-weight: var(#{$css-var-prefix}font-weight);
    font-size: var(#{$css-var-prefix}font-size);
    line-height: var(#{$css-var-prefix}line-height); // 1
    font-family: var(#{$css-var-prefix}font-family);
    text-underline-offset: var(#{$css-var-prefix}text-underline-offset);
    text-rendering: optimizeLegibility;
    overflow-wrap: break-word; // 2
    tab-size: 4; // 3
  }
}

By using CSS variables for customization, the applied styles are evaluated when the element is about to be rendered. This simplifies reasoning about which rule is being applied. This also makes the source files agnostic to file load order during compilation. It's ok for components to depend on variables that haven't been defined yet because they aren't used until "runtime" (at the time of render).

When I browsed components through the web inspector, I found the cascade levels to be shallow and easy to reason about.

:where is used to set defaults with zero specificity. This means any other style definition (element, id, class, inline) would override it.

An example for links:

/*
// matches
<a>Link</a>
<button role="link">Something</button>

// doesn't match
<a role="button"></a>
*/
:where(a:not([role=button])),
[role=link] {
  --pico-color: var(--pico-primary);
  --pico-background-color: transparent;
  --pico-underline: var(--pico-primary-underline);
  /* ... */
}

0 specificity :where(:root) is also used for document level resets shown in the listing above.

There are px defined breakpoints and typography variables are scaled for readability. I like this default for prose, but find it looks cartoonish when interfaces with more forms and app components. The breakpoints can be customized, and there are default ratios defined for font scaling. The same is true for spacing.

There are a handful of svg icons directly embedded into the CSS. A magnifying glass for search, a normalized downward caret for dropdowns for example. I like how these are inlined to avoid additional setup for assets, and also makes them cached alongside the CSS.

What draws me to this project is being able to write semantic HTML with beautiful defaults. Reading the source also gives me an appreciation for how to customize and extend pico.

Learning

• The Easy Way to Pick UI Colors. Sajid. Good refresher on Refactoring UI book concepts.
• Phoenix LiveView - Interactive Apps without Javascript - ElixirConf EU 2019. The Road To LiveView 1.0. Chris McCord. A change in programming model. RPC hiding HTTP request-response over the network. Hotwire Turbo works are a coarser granularity (partials, pages) than LiveView (props). Similar goals of better abstraction of managing client-side state.
• Apple Developer Design Guidelines. Thinking in terms of components and semantics. SwiftUI as declarative ui. Applying different constraints and details on different platforms. Instead of "write once, run everywhere", "learn once, and apply appropriately". Media query and web components are web analogs, but without enough constraints. Reactive prop system under Signals proposal. Done today via libraries (react, svelte)
• Svelte. Reactive props, templates feel like html.

Building

• Tags checkbox filtering with pills. No confusion which label associated with checkbox
• Collapsible search box. Semantic and self contained. Use :focus-within and :placeholder-shown with css animations. Mobile viewport too narrow, hiding title doesn’t work with a nested :not. :before pseudo element doesn’t work on self-closing tags for adding an icon in a search input.
• Dark mode with tailwind dark: utility. CSS variables to constrain permutations. Do we actually need a text-quiet and text-quieter?

$ find public -name '*.css' | xargs du -sh | sort -n

# Baseline 2058e695fa2cac93a48520e85f6ae6d4f2846345
4.0K	public/assets/application.tailwind-2569b4b8.css
156K	public/assets/tailwind-1836982c.css

# After removing @tailwindcss/forms 513a0b726ab6a99ea5d5c59a4fc41178546d214d
8.0K	public/assets/application.tailwind-18ab7e13.css
 88K	public/assets/tailwind-44187fa0.css

# After removing @tailwindcss/typography
8.0K  public/assets/application.tailwind-89bca1fa.css
 68K  public/assets/tailwind-59d86ce3.css

The most common interactions do not justify additional explanations. Take the new liquid glass UI: I use it based on previous experience with touch interfaces and the subtle animations like sliding across a toggle are enough to teach me new behavior. Bigger changes like hiding unknown senders in Messages warrant a popup the first time, and offer a way to switch back to previous behavior. Mail also did this with Categories by offering to go back to having everything in one list.

I've found the best experiences to have sane defaults, combined with quiet discoverable hints to deeper capabilities. It's like how in school, we were taught to "show, not tell" when writing. Yet even recognizing the experiences I prefer, I'm guilty of creating things that explain the obvious, bury the point, and complicate things needlessly.

Here are a couple recent examples.

When I built the weekly and monthly digest notifications for jch.app, I defaulted them enabled thinking it would make them more discoverable. These emails are meant to be a skimmable summary. Roughly 10% of users open emails, about 1% of users click a link to see additional details. 90% of the time, people don't want them. For these users, the best case is the emails are sent to a hidden mailbox, and the worst case is they have to actively click on an unsubscribe link. Having the correct Unsubscribe-List header makes this easier in mail clients, but it's still a mindless task that users shouldn't need to do.

So I've decided to default notifications off for new users. In 2007, notifications were new enough to justify as a highlighted feature. In 2025, they should be behind settings and turned on if useful.

Why keep notifications at all if only 10% of users use it? Well, they happen to be the most active users, even the ones who never click within the emails. Selfishly, I also like the weekly summmary at the end of the week, so I imagine there are some similar minded people. The feature is useful, just not one that needs to be on when someone starts using the app. It should be a discovered feature, not an enabled default.

I was proud of the first iteration of my landing page. It was a simple fast page, with screenshots to preview the app, and prose to explain why someone would want to use it. There's a clear call to action that lets people try out a demo. Here's what it used to look like:

I'm not sure how to measure whether visitors read the prose, but most of my traffic comes from financial-indepence and personal-finance enthusiasts. Users either land in the demo page, then navigate back to learn more, or create an account from the demo page directly. The FAQ is valuable when people want to learn more, but the screenshots weren't necessary because visitors either already previewed the app, or could do so with the "Try it now" button. Here's the new landing page:

For most visitors, there are a few familiar keywords, and a prominent Start > link to jump into the app. I'm not playing the SEO game, and I'd lose even if I tried. For people who want to learn more, the content is just below the fold. Is this too minimal? I'll experiment and tweak to see.

It takes time to understand new interfaces and patterns, so it makes sense to stick with something familiar and gradually ease into better designs.

What else have we become accustomed to, but either no longer need or have better alternatives? (registrations? passwords, notifications) What used to be reasonable defaults, but are now mindless nuisances? (3rd party cookie popups, ask app not to track, notifications, dark mode perhaps?)

Remember jQuery? The interface was so simple, and it proliferated so many plugins that followed a similar design. These were the early polyfills for the modern web platform we know today.

I've switched operating systems, hardware architectures, desktops, laptops, and phones. Somehow, through all of that, a website written 20 years ago still works today. Other than retro-nostalgic emulation, is that true for anything else?

Herman has written a great post on Building software to last forever. As I develop my financial independence jch.app, I'm thinking how I'll make it last forever.

I start with the semantics and affordances of a design with unstyled HTML first. Think text, links, forms, and buttons.

I target Web Platform Baseline and use MDN daily as a resource. Practically, I develop with Safari and Safari iOS because they tend to be the lowest common denominator, and I'm in that ecosystem.

Then I enter my CSS Zen Garden phase. Thankfully, with grid, flexbox, and multi-col layouts in baseline, there are many more tools available than the early days of the web. There's also room for some delightful flourishes with color and animations.

I use tailwind because it lets me prototype quickly. A dependency isn't detrimental to longevity if it lives close to a standard, and doesn't lock into the vendor. I could easily switch back to BEM-style naming and CSS.

If I stopped now, the app should be fully usable and aesthetically pleasing. I sprinkle on Javascript for the final bit of polish. For example, I recently added drag and drop reordering. Initially, I did this with the baseline Drag and Drop API, but found it clunky on touch devices. Much like how jQuery would polyfill capabilities that weren't quite ready for primetime, I add js dependencies sparingly for the same reason.

I use <noscript> wherever I enhance components, and also a .no-js CSS class defined within noscript to help hide UI as needed.

Try turning off CSS and Javascript when visiting jch.app. The default browser styles remind me of Craigslist in a good way. The site works as intended. Turn on CSS. It's a big jump in layout and the experience, but the semantics between pages and functionality stay the same. Finally, turn on javascript. These changes are subtle. Service workers add device-specific native features like push notifications and icons. View transitions adds an extra bit of silkiness to the experience.

I've written about self-hosting jch.app on old hardware. There isn't an infrastructure equivalent of "baseline", but "unix-y" comes close.

My goal was to test jch.app serviceworkers with different devices on the same network. While localhost is an exception allowed for serviceworkers, all other origins require a no-warning https connection. This meant the certificate must be signed with a system trusted CA.

Fortunately, mkcert does exactly that. Some additional fiddling was needed to configure puma with command line options to reference the certs and listen for SSL connections. No additional gems, or configuration changes were necessary. Tested on macOS 15.6.1, puma 6.6.0, mkcert 1.4.4, and rails 8.0.2.

# Run from rails root
# Create locally trusted certificate https://github.com/FiloSottile/mkcert
$ mkcert -install

# Used `sudo scutil --set LocalHostName` to set local hostname to `roboplan.local`
$ mkcert roboplan.local "*.roboplan.local" roboplan.local localhost 127.0.0.1 ::1

# Rename to avoid shell escaping later
$ mkdir -p config/certs
$ mv roboplan.local+5-key.pem config/certs/roboplan.local-key.pem
$ mv roboplan.local+5.pem config/certs/roboplan.local.pem

# Added in bin/dev
$ bin/rails server -b 'ssl://0.0.0.0?key=config/certs/roboplan.local-key.pem&cert=config/certs/roboplan.local.pem'

Puma and Falcon support self-signed certificates with localhost gem, but the defaults did not add a system trusted CA causing certificate warnings that made serviceworkers unavailable.

Additional notes:

• mkcert is a cross platform tool to install a system trusted CA, and use that to sign certs that won't give the insecure warning
• Rails will require localhost the development env without an explicit require
• puma reads from config/puma/development.rb, but does not evaluate the global config/puma.rb
• localhost setup uses bake localhost:install, but does not list bake as a dependency
• puma config ssl_bind still requires starting puma or rails server with -b 'ssl://localhost:9292' to handle SSL. Because of this, I preferred keeping all the config in one place as a CLI flag.
• puma docs start server with puma, but this loses the logging defaults I prefer with rails server
• bin/setup updated with mkcert steps for repeatability
• development certificates added to gitignore since they'll be specific to each host

Service workers are only available in secure contexts: this means that their document is served over HTTPS, although browsers also treat http://localhost as a secure context, to facilitate local development. MDN Service Worker API

• https://github.com/FiloSottile/mkcert
• https://github.com/puma/puma/blob/6-6-stable/README.md#self-signed-ssl-certificates-via-the-localhost-gem-for-development-use puma localhost documentation
• https://github.com/puma/puma/releases/tag/v5.6.0 Support localhost integration in ssl_bind
• https://github.com/puma/puma/releases/tag/v5.5.0 new integration with the localhost gem
• https://github.com/basecamp/thruster/pull/40 TLS_LOCAL support is promising, but also fine to leave thruster focused on production
• https://gist.github.com/chaffeqa/d6c6ac491d3e1824a2980607d796e4a8 creates cert dynamically in config/puma.rb and installs to system across platforms. This had the ssl_bind config, but was missing the -b ssl://0.0.0.0:3001. I found mkcert first, but this implementation may be easier to use with bin/setup and version control.
• https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API

I enjoyed all of the food, except for one ramen place in Osaka and a weird deep fried tuna ball thing. Instead of online reviews, I preferred finding a dense street of restaurants and wandering around. Train stations and malls were good ways to escape the heat, eat, and rest. We didn’t do omakase because the kids were too young, but conveyor belt sushi was delicious, fun, and very affordable. Though breakfast came included in two of our stays, we preferred trying out different onigiri’s and pastries from 7-11, Lawsons, and Family Marts. Breakfast, lunch, and dinners ran around ~1k yen, ~3-5k yen, and 5-9k yen respectively, with only a few meals being significantly more.

Apple Wallet supports Suica transit IC, under 6 is free, but I wish we bought a child card at the before leaving the airport because they validate age with a passport. Some JR Ticket Office (midori no madoguchi) can issue a card, but we didn’t carry our passports after the first day. The kids enjoyed figuring out transit routes and using coins to purchase tickets.

Shinkansen was spacious, quiet, and allowed food. We purchased an extra seat ($300 USD total) for Stella southbound, but it wasn’t necessary and caused us to be seated in different cars. Northbound we bought 3 tickets ($250 USD), which kept us in the same row. The JR pass didn’t make sense for two stops. While we did get snacks for the ride, I was jealous of the luxurious ekiben our neighbors had.

August 5, 2025

Comfort Self Hotel HACHI-EMON

We loved the tatami style room, which allowed us to jump around during the day, and have maximum bed space at night. The lobby downstairs has a vending machine, coffee, and a table to play cards. We arrived before check-in and stored our luggage in the lobby. Having the shower and toilet in separate rooms was convenient in the evenings. The small laundry was useful for humid days, and we air dried washed clothes on the shower rail. We used the small fridge, sink, and kettle in the kitchenette. Shoten-Dori was a walkable street right out front with several restaurants. Fukushima was the nearest JR stop.

We didn’t make it to Abeno Karukas (16th floor museum, tall sky scraper view), Tsutenkaku (neon lights tower), Mega Donki (big grocery store)

• Osaka Castle and Park
• Cup Noodle Museum. Big hit with the kids
• Osaka Garden City is an underground walk / mall that helped with the sun
• Nipponbashi denden town. Not good during day, kind of grungy

August 7, 2025

Shizutetsu Hotel Prezio was a smaller western style hotel room. Compared with the apartment style inn, it felt more cramped because of the larger bathroom with a tub, and bed frames. 7-11 was right across the street.

• Fushimi Inari Taisha. Much cooler on the hike, lot of stairs, but vending machines and rest stops along the way. Everyone made the whole hike.
• Arashiyama Bamboo Forest. We didn’t stay in the forest long. There’s a beautiful pond with lily pads. There were several paid gardens, but kids did not have patience for it. We didn’t try the ‘romance train’ leaving from the forest, but that could’ve been a good way to sit and rest. We also saw tourists on long shallow canoes.
• Monkey preserve is walkable from bamboo forest. A steep hike up. Kids enjoyed feeding the monkeys. I wouldn’t make a separate trip for it, but it’s a good add-on to bamboo forest.
• Samurai museum. Popular with kids, very touristy / kitschy

We didn’t make it to Nintendo Museum (requires advance booking), Manga Museum, Museum of Kyoto, Nara Deer Park (though we did see one while feeding macaque monkeys).

August 10, 2025

We stayed at an Airbnb near Taichiaigawa station on the Keiyu line. While it was close to Haneda airport, and our friend’s place, we with we stayed with our friends to see them more, or chose a more central location in Tokyo. Our place felt cramped because of chairs with backs, a folding leaf table that was missing the piece that held up the leaf, and a too-large refridgerator. Once again, we found the laundry convenient. Wendy took a call on the balcony sitting on the AC one day, and another call in the hallway that could be closed into a room when it was too hot outside. There was an AEON market downstairs, and Taichiaigawa station had Lawson’s, Matsuya, and a take out sushi place.

Big Max and Rin came up with a great itinerary for us. They helped us book Ghibli Museum and TeamLab Planets in advance. They had great picks for vegetarian food too.

• Meiji Jingumae, Harajuku. Shrine, walking down a market street.
• Kamakura beach town, big buddha, great to relax from city for a day
• Ghibli museum. We watched Totoro in advance. Max said Spirited Away was too scary at 5. Fun for kids and adults, short film at the end.
• TeamLab Planets. Water was my favorite. Pack more snacks or make lunch plans b/c ramen was expensive and only ok. Still cheap by US standards.
• Asakusa, Senso-ji, Sky tree, kitchen street

We didn’t make it to kitchen street, sky tree. Many more areas to explore in Tokyo.

• Purchased Nomad e-sim ahead of trip, but easy to pick up airport.
• No need to order currency ahead. Most accept Apple Pay, Suica. No-fee atm for rest.
• Freeze a drink and store in backpack.
• We brought backpack with water / snacks to cut down on trash, but easily could’ve done day trips without.
• Don’t eat and walk.
• No stroller made it easier to access sites, but wish I could’ve had a sling to carry Stella.
• Bring a cloth for sweat and sticky faces and hands.

Personally, I don't mind cron syntax, but it turns out fugit also supports time zones. I have some tasks that run on Eastern time based on the stock market. Previously, I had two separate cron entries for daylight savings time. But now, fugit simplifies it to US/Eastern.

The readme has a lot of other examples, but the fun one that stood out to me was "the first Monday of the month":

Fugit tries to follow the man 5 crontab documentation.

There is a surprising thing about this canon, all the columns are joined by ANDs, except for monthday and weekday which are joined together by OR if they are both set (they are not *).

Many people (me included) are surprised when they try to specify "at 05:00 on the first Monday of the month" as 0 5 1-7 * 1 or 0 5 1-7 * mon and the results are off.

The man page says:

Note: The day of a command's execution can be specified by two fields -- day of month, and day of week. If both fields are restricted (ie, are not *), the command will be run when either field matches the current time. For example, ``30 4 1,15 * 5'' would cause a command to be run at 4:30 am on the 1st and 15th of each month, plus every Friday. Fugit follows this specification.

Anyways, thought I'd share this long-running stable and neat gem that's used by a lot of the popular ruby scheduling libs.

r/rails

I love cars, and have seen a few posts and comments in this sub. Thought I’d share my experiences as a car enthusiast with specific advice for HENRY’s. I have no qualifications in this area, just a guy who thinks about cars and money too much. I’m sure others have smarter ways of doing this, but this is what’s worked for me.

Should I buy one now?

Short answer: No, wait till summer.

Long answer: The pandemic, global supply chain shortages, increased interest rates, and decreased used inventory are all working against the buyer right now. The average new car transaction price peaked in November 2022 at $48k. Supply chain shortages means longer waits or custom orders, or missing features like auto start-stop (a hidden blessing imo).

My experience: I bought a 2022 Jeep Wrangler Willys Sport 4dr last year. I ordered it in April and took delivery in July at MSRP ($40k). It was much more expensive than a year ago when discounts were everywhere, but cheaper than the increased MSRP this year. I had never custom ordered a car before, but getting exactly the trim and color I want (and nothing extra) was a great experience. Everything was done over email until I went in to take delivery. No haggling, no BS, just sign the paperwork and go.

New vs Used

Short answer: Yes.

Long answer: Conventional wisdom says you’ll spend less on a used car, but it’s a set of trade offs. For most high earners in good financial shape, here’s my reasons for choosing new:

New cars have more safety features, both passive safety (stronger materials, more airbags) and active safety (blind spot monitoring, emergency brake). Saving money won’t matter if you’re seriously hurt. IIHS has safety ratings.

New cars have better financing. Manufacturers subsidize new car loans to make them affordable.

Yes, the depreciation curve is sharpest in the first year. But unless you’re constantly switching vehicles, the average is not bad. Edmunds Total Cost of Ownership calculator can give rough estimates over a 5 year span, Kelley Blue Book can give pricing on used cars and what you can expect to sell a used car for.

My experience: Growing up, the first car my family had was a $400 Toyota Corolla Tercel. I loved that car. My parents drove it from NY to CA. Dad taught me to drive stick in an empty parking lot. We drove it until it died, and gave it away to a family who fixed it up and drove it some more. Bang for the buck, I’ll never beat that car. I bought other used cars over the years, and bought my first new car after we had a kid. We’ve had the Mazda 6 for 9 trouble-free years now, and looking at my spreadsheet of costs, it’s been less than some used cars I’ve had in the past. There are old cars I love because of their character, but I’m talking about general transportation tools in this case.

Buy vs Lease

Short answer: Buy, unless there’s an amazing deal on a lease

Long answer: At the end of the day, you’re getting a car for a period of time and mileage for a sum of money. Leasing sets a cap on usage and guarantees you a depreciation cost up front. Buying offers more flexibility.

My experience: I’ve only bought cars, but I’m open to leasing. We don’t commute with cars, so we typically use fewer miles. Fiat 500e for $80/month was a great deal, but we couldn’t fit car seats.

Sometimes it makes sense to lease even if you intend to finance at the end of the lease. When we bought our Mazda in september, we opted to lease because interest rate on the lease (0.29%) was much lower than finance (3-3.5%). So effectively leasing is paying a lower interest rate for three years, then having some option value -Any-Panda2219

Cash or finance

Short answer: Finance

Long answer: Doug Demuro explains this better than I can. On the finance side, it’s good for building up credit, and if you have good credit, you’ll get good rates. Interest rates that are below expected equity return rates also means you’ll have more time in the market. It’ll also smooth out your cash flows.

My experience: I regret not taking 0.9% financing on my Mazda. At that point in my life, I was aiming for “no debt”, even if debt is a good value (I can write more about using debt effectively if there’s interest in a separate post, lots of options open up for HENRYs). For the Jeep, I paid $5k on my credit card that gave me 2.6% cashback and financed the rest with a 2.25% interest-only personal loan. I paid the $5k off immediately with the loan, and kept the cash value of the car in a savings fund yielding 4.3%.

TL;DR

Cars are expensive. Cars can be basic tools, or they can be passionate hobbies. I used to feel a lot of guilt when spending on cars, but after looking at my history, I realize the joy it brings me is worth the money.

comments

When to use debt

My parents viewed debt as a bad thing. The only form of debt they used was a home mortgage, and that was out of necessity. I started with this view initially, but slowly realized that debt is just a tool. There’s good debt that gives you more opportunities, and there’s bad debt that drags you down. This is a pragmatic guide on what debt options are available to HENRY’s and leave it up to you to decide whether an opportunity is worth financing or not.

Credit cards

Good: Rewards Bad: Everything else

I have all my credit cards on autopay. I don’t see them as an effective financing tool because of the high interest rates.

Personal loans / Credit Unions

Good: consolidating debt with higher interest rates

These are unsecured loans that typically have higher interest rates than secured loans, but much less than credit cards.

My experience: I used a 2.25% interest-only loan to buy a car.

401k Loans

Good: Borrow against your 401k, pay yourself back the interest, fast turn around Neutral: plan specific amounts, mine was the lessor of 50% of 401k balance or 50k. Bad: Entire balance due on employment termination.

I’m not sure how common this feature is, but I had it in my last Fidelity 401k. It cost $100 to setup, and funds are ready within 7 days. I didn’t end up using it, but I liked that it was a very liquid and fast option that didn’t require a heavy underwriting process. Note that this is not the same as a hardship distribution. You’re borrowing from your 401k, and making payments back into your 401k. The interest rate you pay also goes back to yourself.

Pledged Asset Lines

Good: Borrow against your portfolio Neutral: interest-only or amortized options, fixed or variable rates Bad: Beware margin calls during market downturns

These are basically margin loans, but with more attractive rates and terms depending on your relationship with your custodian and how much assets you have with them. Morgan Stanley had a product called Liquidity Access Line that allowed you to have a fixed rate.

Mortgages / HELOCs

Good: home buying, mortgage interest deduction

It pays to shop around. I liked using a mortgage broker because he found better rates than I could. I did not like using any of the mortgage quote sites. If you do use one, use a spam email or google voice account because they’ll spam you for a long time.

Specific to HENRY’s, work out how much the mortgage interest deduction and property taxes can save you on federal taxes.

Rate discounts

Look for discounts from having status at a particular bank. For example, Bank of America offers discounts on loan fees, HELOC’s, and auto loans based on how much assets you have with them.

Credit Scores

Having a good credit score helps you get better loan rates. I used to use CreditKarma for tracking scores, but noticed that banks include the scores now. Annual Credit Report is a terrible site, but is actually the official way to dispute any past credit issues, or put a credit freeze.

TL;DR

HENRY’s shouldn’t be afraid of debt. It’s a tool that helps you manage cash flow, and sometimes comes with tax benefits.

comments

The High Earning part of HENRY’s benefits from minimizing taxes. I am not a tax professional (though I’ve considered taking the EA tests and becoming one for friends). I’m sure there are smarter people out there with better strategies, and different situations. This is just what’s worked for me over the years.

Tax advantaged retirement accounts

Short version: Max out contributions to all tax advantaged accounts before starting a brokerage account.

The IRS has a great overview of the types of retirement plans. Even in plans without matching, long vesting periods, or high fees, I’ve found the instant tax savings and additional contributions justifies the cost, especially if you’re in a high income tax state on top of high federal taxes. Tax efficient fund placement is also a good read.

Traditional vs Roth

Short version: Contribute to traditional plans at 22% marginal tax rate and above, Roth otherwise.

The r/personalfinance wiki has a great page on traditional vs roth. Both are great options. I built a spreadsheet and so have many others, but there are enough variables that it’s more important to be headed in the right direction, than to be precisely right (impossible b/c unknown future rates). My “a-ha moment” was realizing that traditional accounts gets you tax savings at your highest marginal tax rate, and you start paying taxes from your lowest tax bracket progressively.

Health savings account HSA

Short version: Max it out

I was on the fence about HSA’s for 2 reasons.

1. I was worried I would contribute too much, and not have enough medical expenses to use it up.
2. I was worried about keeping track of receipts for reimbursements.

For both these points, if I don’t use it all for medical expenses, after age 65, I can take distributions out and pay tax on it. Even if I take distributions out before 65 and take the 20% penalty, there’ll be decades of compounding growth for a one time 20% penalty. For example, $100 invested at 5% annual compounding will give you $128 on the 5th year. If you take a 20% penalty ($128 * 0.20 = $25.6), you’re still breaking even. Over long timelines, and higher returns, I don’t worry about the 20% penalty. If I don’t withdraw till 65+, it’s a non-issue. Fidelity has even more details and benefits in their guide. I also rolled over my old HSA’s into Fidelity because they don’t charge fees, and the have great investment options.

529 College Savings

Short version: Yes if you have kids

Similar thinking as HSA. No immediate tax savings, but savings on distribution. If I overcontribute, the penalty won’t be that bad after 18 years of growth.

Required minimum distributions RMDs

Short version: Don’t worry about it until you stop being a high earner

If our income taxes decrease, that’s when we’ll roll over traditional accounts to Roth. There’s also no guarantee RMD rules won’t change in the future.

Backdoor contributions

Short version: Yes, do backdoor roth IRA, and mega backdoor 401k if available

Donor advised funds DAF

Short version: Use them to smooth out high tax years

Again, I like Fidelity’s guide and their account. I used DAF’s to gift appreciated stock on a high income year. It’s a tool to help control which years you want to take a tax deduction on charitable giving.

Tax loss harvesting TLH

Short version: Yes, but it doesn’t save as much as you think

Kitces has a good explanation that covers the actual value of tax loss harvesting. I learned how to do it by signing up for a robo-advisor and observing it for a year. After a year, I decided to manage it myself and skip the fee. I don’t think robo-advisors charge too much, but the assets under management pricing model doesn’t make sense for TLH. When talking about broad ETFs, they become less likely to have losses over time. However, you’re going to pay for all assets under management. I use jch.app to track holdings and also as a rebalance tool.

Real estate

I don't have experience in real estate other than itemizing taxes and claiming depreciation and property taxes. I'm aware of 1031 exchanges, qualified opportunity zones, but don't have personal experience. I'll update this section if there's good info from the comments.

TL;DR

A good piece of advice my friend gave me: “Taxes shouldn’t be the primary reason for you doing something, but it’s good to be aware of it”. How this works in practice is I have my primary objective: buy a home, invest for retirement, and then decide how taxes play into it.

DM me other HENRY topics you’re interested in?

Bonus: for anyone who’s interested in tax policy, I loved “A Fine Mess: A Global Quest for a Simpler, Fairer, and More Efficient Tax System” by T.R. Reid. It’s a fun read, and I liked it’s survey of different tax systems, and the concept of “broad base, low rates”.

comments

While there is a grid-template-rows: masonry, it is not widely available in 2025. I wanted a single column of items on mobile, and 300px wide columns added as the viewport allowed. Items would have auto width and height, and allow the columns to determine width:

#container {
  columns: 300px;
  gap: 1em; /* inline axis gutter */
}

.item {
  box-shadow: mintcream 3px 3px;
  margin-bottom: 1em; /* block axis gutter */
}

<div id="container">
  <div class="item">First</div>
  <div class="item">Second, with more stuff</div>
  <div class="item">Third, and a whole lotta more so it wraps when viewport is small</div>
  <div class="items">Fourth, because why not</div>
</div>

This worked great! Kinda. But then I noticed an extra line and gap would appear in the new column when the viewport widened. It didn't show up in the web inspector, but some fiddling narrowed down box-shadow to cause the unwanted line, and margin-bottom to cause the excess gap. This only occured on Safari (mobile and desktop). I found several related issues on bugzilla, but the ones with the most context are:

• Bug 14137: box-shadow on element inside multi-column doesn't draw outside column boundary
• Bug 104944: CSS Fragmentation Implement correct margin truncation at breaks

I've linked to my comments with the reproduction HTML and CSS.

I was open to removing the box-shadow or changing it to an inset shadow, but the CSS fragmentation bug affecting margins is a dealbreaker because it causes the boxes to not line up at the top for multiple columns. I tried using margin collapsing by setting margin-block: 2.5em, which collapsed fine within the same column, but didn't work on the first item of the new column. I also tried to wrap my items and use padding for gutters rather than margins, but padding would also push into the top of new columns (womp womp).

Multi-column is still useful for prose, and content that doesn't require alignment, but unfortunately does not work in Safari for a masonry layout of cards. Long term, using the masonry grid layout is the right way to go, but I was hoping this would provide a simple CSS-only fallback.

Similar to physically tiding up, I like to keep our finances tidy too. But unlike the necessary daily tidy in my home with two kids and a dog, the financial tidy happens once a month and takes around 10 minutes most months. I follow up on long running things, fix miscategorized transactions, and squint to see if anything weird stands out.

I use Empower (formerly PersonalCapital, previously Mint) to aggregate spending across different accounts. I export to CSV because account syncing breaks occasionaly or I fat-finger something and lose history. Then I import the data into an app I made to review spending. I sit down with a Lipton tea, and go over my notes:

• Last month: review e.g. Did locksmith get reimbursed?
• This month: take notes. e.g. 4/1 paid estimated tax $X,XXX
• Future months: make sections for upcoming items. e.g. December 2025 property tax $X,XXX https://..., October check 401k
• Categorize transactions: easier to remember or look up when things are fresh
• Sort, filter, review any large transactions

For spending categories, I use a few broad categories rather than many granular ones; 'Home' includes mortgage, HOA dues, repairs, property taxes. 'Utilities' includes phone, internet, water, trash, electricity. Last year, the top 3 categories accounted for 75% of our spending, the top 5 for 85%. It's easier to remember fewer categories and consistently label things. Outside of the top categories, there's a 'General Merchandise' category for any one off things. It ends up being 1-3% of our spending in recent years, so not worth breaking down into better categories. If an expense could be multiple categories like a rental car (Automotive, Travel), I just pick one. Over time, the categories may change (Automotive and Hobby merged to Automotive), but they're similar enough in recent years to highlight big year-over-year changes. If I'm looking for something specific within a broad category, I can filter then search (Utilities, search for T-mobile).

Transfers between accounts are categorized transfers and cancel each other out. Credit card payments are listed to make it easy to look up payment dates, but aren't counted as an expense because individual transactions already cover that. Other transfers include saving for retirement or college.

I keep track of estimated income tax payments, but don't include them in our spending. I want to know how much money we need to cover our expenses, but income tax varies with income. No income, no income tax either. I do include property tax in our spending because that needs to be paid even if we don't earn income.

I track investment dividend dates to help manage our cash flow, making sure we have enough cash on hand for a year of expenses. Cash beyond a year's expenses goes towards investments.

I don't try to distribute big expenses across months. For example, home property taxes and insurance is paid twice a year. It makes those months look heavy in spending, but I'm more interested in 1-year spend, or running 12-month average spending. I don't find comparing month to month spending useful, preferring to look at the bigger annual picture (2023 vs 2024).

Whatever the software and tools, keeping a monthly schedule has worked well for me. I keep some other notes on personal finance at jch/personal-finance.

Since leaving my job and starting to build software for fun again (jch.app), I've slowly rediscovered that original joy of computing, from software down to hardware. I've dusted off the cobwebs off this blog, adding RSS and dark mode. I installed Debian Bookworm (my last linux was, checks notes, Debian Woody, released July 2002) on a e-waste Thinkpad T480s (thanks Dad!). Production is hosted on a 2016 macbook pro with a dead battery and a set of bash scripts (yolo).

I still love Apple hardware, but when there isn't the pressure of deadlines, it's more fun to figure things out along the way.

During covid, I ran out of yeast. I tried to make my own sourdough starter from flour and water, but ended up with a hoochy moldy mess.

Fast forward a couple years, and my friend Sarah was kind enough to share her starter, idiot-proof care instructions, and a recipe. I named the starter Lemmy, because it was lemon-y fresh.

The first few loaves were edible, but definitely looked "homemade" in the bad way. I started writing down notes on temperature, ferment times, and other observations in a note on my phone. It gave me the warm fuzzies to see and taste each loaf after the string of initial failures. If you want a piece of Lemmy to try to bake your own bread, I'm happy to mail you some dehydrated starter to start your own.

I made a webpage to organize my recipe and notes offline. I took inspiration from a blog program named Blosxom that was written as a single perl script. I liked the idea of having everything self contained within a single file. My take was to create a single HTML file with styles and javascript inlined into the markup, requiring only a browser, but not requiring an internet connection. It currently sits at ~44kB, or around ~10kB gzipped. I load a couple of fonts, and some sample journal entries, but these are optional and the page works offline without them. Since it's a simple app, I wrote the CSS without tailwind, and the javascript without dependencies. I use IndexDB to store images and bake notes, and allow these to be exported and imported. On mobile devices, photos are taken with the input capture attribute.

I made a simple responsive grid layout and tested it across mobile, tablet, and desktop sizes. I spent some time learning grid, but I'm still not satisfied with how to layout a tall element in the same row track as shorter elements. I have the tall element span several row tracks because masonry layout isn't widely available, and I still want the bake photos to line up against row lines. Please write me if you know of a better way.

2025-05-05: CSS Multi-Column Layout sounds promising. MDN

• popover: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover
• dialog: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
• https://stackoverflow.com/questions/79501074/focusing-input-blocks-page-on-safari-when-part-of-element-with-popover-api

Anchor positioning is in technical preview for Safari and available for 71% of browsers. I had planned to make the modal sheet stick to the bottom on small viewports (easy without anchors), and near the trigger in larger viewports (anchors necessary because it's in the top layer). But after testing on the simulator and devices, I found that iOS Safari has a not-quite-keyboard sized element on the bottom of the HTML element that I cannot prevent scrolling when an input is focused.

I've seen this on several other sites, and it's a nitpick but annoying enough to me I would make the modal feel like the web rather than try and emulate a native modal sheet.

I'd like to revisit anchor positioning for some of the filter menus.

• https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning
• https://developer.mozilla.org/en-US/docs/Glossary/Top_layer
• https://caniuse.com/css-anchor-positioning

Here are changes since I last looked at this topic:

• Rail's ActionCable abstracts websocket connection management
• Turbo streaming can work through websockets or eventsource
• ActionController::Streaming can stream layouts earlier with some caveats around middlewares and layouts
• falcon is a newer async ruby web server

• rack-stream: https://github.com/jch/rack-stream/
• HTTP Streaming: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
• You might not need Websockets: https://hntrl.io/posts/you-dont-need-websockets/
• ActionCable: https://guides.rubyonrails.org/action_cable_overview.html
• Turbo Streams: https://turbo.hotwired.dev/handbook/streams
• ActionController::Streaming: https://api.rubyonrails.org/classes/ActionController/Streaming.html
• falcon: https://github.com/socketry/falcon

On iOS mobile safari 18.3.1, the form in the modal freezes up after the date picker makes a selection. It's as if the modal itself becomes inert.

My hack workaround is to scroll the page by a pixel when the input loses focus onblur. This seems to unfreeze the page. Note this hack is only needed if a page is saved to the home screen as a PWA. It works fine from Safari mobile.

<dialog>
  <form>
    <label>
      Purchase date
      <input type="date" onblur="window.scrollBy(0, 1);">
    </label>
    <label>
      Shares
      <input type="number">
    </label>
    <input type="submit">
  </form>
</dialog>

body {
  max-width: 80ch;
  padding: 1em;
  margin: auto;
}

.highlight pre {
  border-left: 2px solid palegoldenrod;
  padding-inline-start: 0.75em;
}

.pl-c {color: darkgray;}
.pl-c1, .pl-s .pl-v {color: deepskyblue;}
.pl-e, .pl-en {color: mediumslateblue;}
.pl-s .pl-s1, .pl-smi {color: gray;}
.pl-ent  {color: mediumseagreen;}
.pl-k {color: coral;}
.pl-pds, .pl-s, .pl-s .pl-pse .pl-s1, .pl-sr, .pl-sr .pl-cce, .pl-sr .pl-sra, .pl-sr .pl-sre {color: deepskyblue;}
.pl-v {color: salmon;}
.pl-id {color: coral;}
.pl-ii {background-color: coral; color: black;}
.pl-sr .pl-cce {color: mediumseagreen; font-weight: bold;}
.pl-ml {color: goldenrod;}
.pl-mh, .pl-mh .pl-en, .pl-ms {color: deepskyblue; font-weight: bold;}
.pl-mq {color: deepskyblue;}
.pl-mi {color: gray; font-style: italic;}
.pl-mb {color: gray; font-weight: bold;}
.pl-md {background-color: mistyrose; color: coral;}
.pl-mi1 {background-color: honeydew; color: mediumseagreen;}
.pl-mdr {color: mediumslateblue; font-weight: bold;}
.pl-mo {color: deepskyblue;}

@media (prefers-color-scheme: dark) {
  body {
    background-color: black;
    color: snow;
  }

  a {
    color: aqua;
  }

  a:visited {
    color: orchid;
  }

  a:hover, a:focus {
    color: lightsalmon;
  }

  a:active {
    color: lightcoral;
  }
}

I added a new bin/publish_rss for feed readers and validated with W3C.

From https://inclusive-components.design/a-theme-switcher/

:root {
   background-color: #fefefe;
   filter: invert(100%);
}

* {
   background-color: inherit;
}

img:not([src*=".svg"]), video {
   filter: invert(100%);
}

@media (prefers-color-scheme: dark) {
  body {
    background-color: black;
    color: snow;
  }

  a, a:visited { color: #0df; }
}

I broke with tradition in 2022 and purchased a 13 mini thinking it would better capture family and travel photos, while still keeping the small form factor. While it's still a good phone, my original reasons for upgrading hasn't really panned out. The photos are better in low light, but for the quick point-and-shoot food/kid/dog photos, I'm not missing much. The phone's still small, but it's thicker than the SE, feeling bulky in jeans. The tiniest tiny annoyance is that it doesn't sit flush on a flat surface without a case (it does with the Apple case). The screen is larger without the bezels, but personally, I didn't mind the small screen of the SE.

Which brings me back to today's announcement for the 16e. I'm sure it'll be faster, brighter, longer lasting, and also familiar. I'm excited about having usb-c (projected year for everything in the house standardizing to one port, 2035), longer battery, and a relatively small phone. The big splash continues to be Apple intelligence, but I'm fine with waiting a few years for apps to make meaningful use fo the new hardware. Having the latest hardware in the budget iPhone means being able to take advantage of the full software support lifecycle. Apple promises 5 years, but there's been iOS releases good for 7-8 years in some cases. The battery will degrade with daily use, but even accounting for a battery swap at year 3, that would mean keeping a functional device 6 years through 2031.

I saw on the product page that AppleCare has switched over to a subscription plan for $10/mo, $100/year, or $190 for 2 years. There's a $29 glass deductible, $99 damage, and $149 for theft or loss. I would skip this and pay the premium for their case, and pony up for the battery replacement halfway through. For my 13 mini, it's a reasonable $89, and the 16 previews the cost at $99.

While there's always going to be marketing for the latest and greatest, I find the budget iPhone appealing for it's longevity and price. For $700 including a battery change, one can start with a hardware package that can comfortably last 5 years, and possibly stretch further.

I haven't pushed ownership this far because of battery degradation, but I plan to try with the 13 mini. It still feels fresh after 3 years. The battery health is at 88%, but not an issue with fast charging and my use case. The degradation will accelerate with the additional charging, but if it's lasted 3 years already, swapping it now will mean another 2-3 years with a fresh pack.

Here's the basic form.

<!-- GET /securities -->
<search>
  <form action="/securities">
    <input type="search" name="q" placeholder="Search" autocomplete=off spellcheck=false />
    <button>Search</button>
  </form>
</search>

If a user wants to see the price of VTI (Vanguard Total Market Index Fund), they would enter 'VTI' and hit enter, or click 'Search'. A few observations:

1. The default method for a form is GET, so submitting this form takes the browser to /securities?q=VTI
2. button is associated with the form and submits by default
3. <search> hints for screen readers, and/or add a role=search on the form
4. spellcheck=false turns off the angry squiggles in Edge because VTI isn't a word

On the backend, I take the q parameter, do a database lookup, and render the same template with the search results below. Each search result will have a name, full name, current price, and percentage change today.

The plan was to layout each search result like:

+-------------------------------------+
| VTI                         $301.30 |
| Vanguard Total Market I...   -0.30% |
+-------------------------------------+

This layout can be made with flexbox or grid. I experimented with both and found flexbox to be easier to read.

The entire page has a maximum width for readability to keep the name and price close enough. I've focused on a mobile layout, but this could turn into an <aside> sidebar in the future. One highlight is to change grid/flex item's default min-width to stay inside the container and allow text-overflow to work.

<style>
  main {
    max-width: 350px; /* for readability */
    margin-inline: auto; /* centers the container on wider viewports */
  }
</style>
<main>
  <form>...</form>

  <!-- full width so results with short names stretch -->
  <div id="search-result-list" class="w-full">
    <!-- flexbox or grid here -->
    <div class="search-result">
      ...
      <style>
        .fullname {
          whitespace: nowrap; /* so search results have a consistent height */
          min-width: auto; /* or zero b/c the default for flex/grid items is `fit-content` */
          overflow: hidden; /* prevent long names from colliding into the prices */
          text-overflow: ellipsis; /* add the `...` */
        }
      </style>
      <p class="fullname">Vanguard Total Market Index Fund</p>
      ...
    </div>
  </div>
</main>

Once I had search results, the next piece was 'watching' or 'unwatching' a stock. Each watched stock would have a check next to it, and clicking on that would toggle whether it was watched.

+-----+-------------------------------------+
+ [x] | VTI                         $301.30 |
+     | Vanguard Total Market I...   -0.30% |
+-----+-------------------------------------+

My first idea was to build this as a checkbox and enhance it with javascript to submit on click. However, I realized it makes sense to watch one stock at a time. The default behavior for a <button> within a form is to submit the form, skipping the need for javascript.

<div class="search-result">
  <form action="/securities" method="post">
    <button aria-label="Watch VTI">&plus;</button>
  </form>
  <!-- security details -->
</div>

Testing it in a screen reader, I liked having the name of the action with the name of the security announced. I played around with having the button on the left vs right, and found it more aesthetic and intuitive on the left close to the name. It felt like you're "watching VTI". The tab order also felt natural, allowing user to navigate each result and it's details. I could use flex-direction to flip the order and make a left-handed or right-handed setting. With my iPhone 13 mini, it's a natural reach for the button, but something to consider for different devices.

Visually, I used html entities for + and ✓ to represent whether something is watched. I've recently enjoyed using html entities, and emoji as icons rather than svgs or images. There are differences across platforms, but they present a familiar representation specific to the platform. So a check mark looks different in Safari vs Chrome, and different still on Edge on Windows. But each of those will look familiar to users on that platform. It's also easier to maintain because what's rendered matches what's in code.

Speaking of icons, I added a magnifying glass emoji to the left of the search input. It's less customizable than an svg icon, but I found it visually pleasing. I reduced the opacity so it wasn't shouting for attention. I started with a small shadow on the search input to give it a raised look, but once I added the magnifying glass, I went for a minimal single bottom border.

At this point, the search form works. It doesn't need javascript. It uses vanilla HTML elements and attributes that works across browsers. The markup has aria attributes to add semantics for assistive technologies, and doesn't mess with the logical ordering of elements.

To enhance the user experience, I use Turbo to add:

1. Search as you type
2. Morphing elements for smoothness
3. Subtle animations
4. Live preview of stock prices

To implement search as you type, I submit the search form when the input changes oninput="this.form.requestSubmit()". This is the one line of javascript that I wrote. I considered debouncing the events to avoid too many requests to the backend, but found it unnecessary once I limited each search to ~10 results. Between search as you type, and the search icon, I removed the 'Search' button to reduce clutter further.

There is a distinction between form.submit and form.requestSubmit. The latter works as if a user clicked submit, which is necessary for Turbo.

Each search input change adds to the browser history. So a search for 'VTI' adds:

1. /securities?q=V
2. /securities?q=VT
3. /securities?q=VTI

Adding data-turbo-action="replace" on the form configures it replace the entry in the browser history rather than the default advance that adds a new entry on the stack.

Turbo's default behavior on forms and links adds subtle animations between page transitions. Since the search form renders the same page when it's submitted, I enable morphing:

<head>
  <meta name="turbo-refresh-method" content="morph">
</head>

With search results limited to 15, there weren't enough elements to make a noticeable difference even when I typed or cleared the input quickly. One side effect is that the search input is not replaced between different pages. However, I left a data-turbo-permanent attribute on the input because it documents that the element should be kept between turbo visits, and won't regress if I change the refresh method back to the default. This was also necessary for autofocus to not reset the cursor position.

There's additional opportunity to use view transitions to fine tune the search results instead of the default cross fade, but again, it didn't seem worth the effort with a capped number of results.

Here's the final search as you type form without styles for readability. Note the input value comes from the backend, but can also be populated with javascript from window.location.search. Though the latter would make it tricky to maintain cursor position.

<form id="search-form" action="/securities" data-turbo-action="replace" data-turbo-permanent>
  <input name="q" type="search" value="<%= params[:q] %>" placeholder="Search" oninput="this.form.requestSubmit()" autofocus autocomplete="off" spellcheck="false" />
</form>

When search finds a result, it's nice to preview the current price and today's change percent. My backend tracks this information, and I push new price information via Turbo Streams. This can be done without Rails as the backend, but Rail's ActiveRecord, ActiveJob, and ActionCable integrates with Turbo Streams to provide a nice interface.

<!-- rails helper turbo_stream_from generates subscription -->
<!-- <%= turbo_stream_from "security_1" %> -->
<turbo-cable-stream-source channel="Turbo::StreamsChannel" signed-stream-name="somelongsignedstreamname"></turbo-cable-stream-source>

Turbo Streams documentation says it's implemented with websockets with a fallback to server-sent events (SSE), but I have not tested this. It's out of scope for this article, but here's a taste of what my backend looks like:

class Security < ApplicationRecord
  # this renders securities/_security.html.erb to the "security_1" channel above
  # and replaces search results by unique id selectors that describe each security
  after_update_commit { broadcast_replace_later_to self }
end

At first I had a stream for securities. While this doesn't leak any user specific information, it causes unrelated updates from other searches to be pushed on the same stream. I was worried creating 10 streams on a page would create 10 separate connections to the backend, but it multiplexes the different stream names on a single websocket connection.

Once I had a working version, I tested on different devices and screen readers to add the tweaks and enhancements I talked about so far. But there were two dead ends, display: contents and styling table's, where I learned a lot about accessability.

Safari's web inspector has a menu to disable images, css, and javascript. I toggled these while building to understand what the default user agent experience looked like. Since I'm targeting modern browsers, it's safe to assume CSS and JS are enabled, but it's satisfying to know the page works without them. While I was building the form to watch/unwatch stocks, I thought <fieldset> and <legend> would be a good descriptive pair of tags to use. Since legend must be a direct child of fieldset, I wanted to use flexbox to position the legend, and display: contents to ignore the fieldset and treat it's children as flex items of it's parent.

<form action="/securities" method="post" style="display: flex">
  <fieldset style="display: contents">
    <legend>VTI</legend><!-- valid -->
    <div class="search-result">
      <legend>VTI</legend><!-- invalid, legend must be direct child of fieldset -->
      <button aria-label="Watch VTI">+</button>
      ...
    </div>
  </fieldset>
</form>

MDN warns that browsers incorrectly remove display: content element from the accessability tree. I also realized there's no semantic value to have a fieldset/legend. The only form action is the button, which has an obvious aria-label. The fieldset isn't being used to group a set of related inputs, and the legend is redundant because it's rendered by a shared template again below the button.

I learned:

1. The default user agent styling for fieldset/legend looks good, and allows for interesting transforms and animations.
2. Avoid display: content for now

Next, I considered marking up the search results as tabular data.

<table>
  <legend>Search results</legend>
  <tr>
    <th>Watch</th>
    <th>Name</th>
    <th>Full name</th>
    <th>Price</th>
    <th>Percent change</th>
  </tr>
  <tr style="display: flex">
    <td><form>...</form></td>
    <td>VTI</td>
    <td>Vanguard Total Market Index</td>
    <td>$301.30</td>
    <td>-0.30%</td>
</table>

Unfortunately, this made it difficult to share a template with other pages because "Watch" is a state that's tied to a specific user, while price information is not. With a <div> search result, the template can be shared and the user-specific state can be added, but the same could not be done with a <tr> as the shared template:

<!-- shared.html: shared template for a security -->
<div id="VTI">
  <p>VTI</p>
  <p>Vanguard Total Market</p>
  <p>$301.30</p>
  <p>-0.30%</p>
</div>

<!-- add user specific state and reuse shared template -->
<div class="search-result" style="display: flex">
  <form>(Watch / Unwatch)</form>
  <%= render "shared" %>
</div>

Changing the display on a table removes it's table semantics from screen readers. I didn't change the table's display, only the <tr> to layout individual search results. Nevertheless, I was forcing a table for accessability, then styling it to not be a table.

Play with it at https://jch.app/demo. I encourage you to try turning off javascript and CSS. Try it in a screen reader.

Plain built-in HTML has the flexibility to create useful pages that are accessible by default. Though javascript is widely available, it is not a requirement for building a beautiful and useful page.

A sparing use of javascript can progressively enhance the user experience without increasing complexity and maintenance. The only js I wrote was this.form.requestSubmit(), while the rest were html data attributes to customize Turbo's default behavior.

While my backend is Rails, which has helpers to integrate with Turbo, the concepts and code can be done with any backend. I've even used Turbo on static HTML pages to smooth the transitions between links.

• MDN HTML elements reference: https://developer.mozilla.org/en-US/docs/Web/HTML/Element
• : https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search
• form#method: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#method
• button#type: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#type

• display: contents: https://developer.mozilla.org/en-US/docs/Web/CSS/display-box
• Appendix B: Effects of display: contents on Unusual Elements: https://drafts.csswg.org/css-display/#unbox
• More Accessible Markup with Display Contents: https://hidde.blog/more-accessible-markup-with-display-contents/
• display: contents is not a CSS Reset: https://adrianroselli.com/2018/05/display-contents-is-not-a-css-reset.html
• Table CSS Display Properties and ARIA: https://adrianroselli.com/2018/02/tables-css-display-properties-and-aria.html
• table-layout: fixed: default is fit-content. This allows columns to shrink.

• form.requestSubmit: https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit
• Turbo: https://turbo.hotwired.dev/
• Turbo morphing: https://turbo.hotwired.dev/handbook/page_refreshes#morphing
• Turbo streams: https://turbo.hotwired.dev/handbook/streams

• Enable fullpage accessibility tree: https://developer.mozilla.org/en-US/blog/aria-accessibility-html-landmark-roles/
• Mac Voice Over Cmd F5, Control Option U: https://support.apple.com/en-za/guide/voiceover/vo35709/mac

• turbo-rails Turbo::Broadcastable: https://www.rubydoc.info/gems/turbo-rails/0.5.2/Turbo/Broadcastable
• https://github.com/hotwired/turbo/issues/1093: turbo-rails does debouncing on the backend

I feel warm and fuzzy keeping this 8 year old mac out of the e-waste bin. The app is low traffic, but it nonetheless strained the $7/month Digital Ocean VPS. While it's no Apple silicon or raspberry pi in efficiency, the laptop draws a modest 15-20W, translating to ~$3/month at my utility rates. This generation mac had 4 thunderbolt ports, so I also bought a $10 thunderbolt to ethernet adapter.

I kept the existing OSX install to keep my development and production environments similar. While I love linux, I wanted to avoid troubleshooting apple hardware issues. My dad gave me a free thinkpad t480s which would make a nice linux dev machine, but that's a story for another day.

Roughly, the steps are:

1. DNS resolves your domain name to your server IP address
2. Router forwards requests to your server
3. Server knows to update DNS if IP address changes

My notes list the domain as m.jch.app because the base domain jch.app pointed at production. Once everything was migrated, I updated the configs to point at the base domain.

1. Configure router to assign a static IP address to server by it's MAC address
2. Forward public web (80, 443) and ssh (22), or all ports to server.

By default, Safari uses Private Relay which will mask your public IP if you try to search for it.

# `what is my public ip address command line`
$ curl ifconfig.co

- Router settings
  - Device Info
    - WAN (PUBLIC_IP x.x.x.x)
  - Advanced Setup
    - Static IP Lease, server MAC address, 192.168.1.2 (some static IP)
    - NAT
      - DMZ Host 192.168.1.2 (this updates without a reboot, forwards all ports to this host)

# verify port forwarding works from somewhere outside of your network
$ nc -zv PUBLIC_IP 22

I'm using Cloudflare for DNS, which has an API.

• https://github.com/qdm12/ddns-updater
  • v2.8.1 static binary
  • config/data.json for cloudflare config

  {
    "settings": [
      {
        "provider": "cloudflare",
        "proxied": true,
        "zone_identifier": "cloudflare dash > m.jch.app > scroll down to Zone ID",
        "domain": "m.jch.app",
        "ttl": 600,
        "token": "cloudflare dash > m.jch.app > API > Get your API token > Edit Zone DNS",
        "ip_version": "ipv4",
        "ipv6_suffix": ""
      }
    ]
  }

• Cloudflare > m.jch.app > DNS
  • Verify A record m.jch.app points to PUBLIC_IP

• OSX > Network
  • Ethernet device
    • Verify IP 192.168.1.2 statically assigned by MAC
  • Firewall enabled
    • Options (each should prompt to be added as exception)
      • ddns-updater_2.8.1_darwin_amd64
      • ruby
      • thrust
  • /etc/hosts
    • 192.168.1.2 m.jch.app (otherwise built-in router httpd will respond)

# Gemfile
gem "thruster"  # https://github.com/basecamp/thruster

# config/application.rb
config.hosts << "m.jch.app"
config.logger = Logger.new(config.paths['log'].first, 1, 100.megabytes)

# config/environments/production.rb
# assets will be cached by thruster
config.public_file_server.enabled = true
config.public_file_server.headers = {
  'Cache-Control' => 'public, s-maxage=31536000, max-age=15552000',
  'Expires' => 1.year.from_now.to_formatted_s(:rfc822)
}

# config/master.key from digital ocean

# Starting server in development for testing
$ DEBUG=1 TLS_DOMAIN=m.jch.app thrust bin/rails server
$ curl -Iv https://m.jch.app

# Starting server in production
DEBUG=1 TLS_DOMAIN=jch.app caffeinate -s thrust bin/rails server -e production
$ curl -Iv https://m.jch.app

Previously, I had deployment setup with Kamal and containers. With development and production being the same, I wrote a bash script for simplicity. Deploys take ~13 seconds.

#!/usr/bin/env bash
# bin/deploy
set -e

APP_ROOT=$(dirname "$0")/..
cd $APP_ROOT
source $APP_ROOT/.env

git stash > /dev/null

echo "Pulling the latest changes..."
git pull
echo

echo "Bundling dependencies..."
BUNDLE_DEPLOYMENT=1 BUNDLE_WITHOUT=development:test BUNDLE_WITHOUT_DOCUMENTATION=true bin/bundle
echo

echo "Migrating the database..."
bin/rails db:migrate
echo

echo "Precompiling assets..."
bin/rails assets:precompile
echo

bin/rails runner "puts 'Checking app loads...'"
echo

echo "Restarting the app..."
touch tmp/restart.txt
echo

echo "Cleaning up old logs..."
rm log/*.log.* 2>/dev/null || true
echo

These are run in a screen session for access via ssh. caffeinate keeps the mac awake.

cd ddns-updater; ./ddns-updater_2.8.1_darwin_amd64
cd roboplan; DEBUG=1 TLS_DOMAIN=m.jch.app RAILS_ENV=production WEB_CONCURRENCY=4 RAILS_MAX_THREADS=1 caffeinate -s thrust bin/rails server
htop  # F4 Filter 'puma'
cd roboplan; tail -f log/production.log

$ crontab -l
0 8 * * 1-5 /Users/jch/roboplan/bin/backup

#!/usr/bin/env bash
# bin/backup
set -e

APP_ROOT=$(dirname "$0")/..
source $APP_ROOT/.env

if [ -n "$1" ]; then
  BACKUP_ROOT=$1
else
  BACKUP_ROOT=$APP_ROOT/backups
fi

mkdir -p $BACKUP_ROOT
ls -t $BACKUP_ROOT | tail -n +11 | xargs rm -rf

BACKUP_DIR=$BACKUP_ROOT/${POSTGRES_DB}_$(date +%Y-%m-%d)
NUM_JOBS=$(/usr/sbin/sysctl -n hw.physicalcpu 2>/dev/null || echo 1)

pg_dump $POSTGRES_DB --format=d --jobs=$NUM_JOBS --clean --no-owner --if-exists --file $BACKUP_DIR > /dev/null

find $BACKUP_ROOT -type d | xargs du -sh

• ruby 3.3.5
• rails 7.1.2
• postgresql 17.0
• disable wifi to ensure testing on ethernet interface
• run multiple times to warm up servers

# 1 worker, 3 threads (baseline from digital ocean)
$ wrk -t10 -c100 -d30s https://m.jch.app
Running 30s test @ https://m.jch.app
  10 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    41.68ms   93.04ms   1.81s    99.34%
    Req/Sec    23.56     14.24    70.00     68.77%
  2510 requests in 30.08s, 46.16MB read
  Socket errors: connect 0, read 0, write 0, timeout 234
Requests/sec:     83.43
Transfer/sec:      1.53MB

# 4 workers, 1 thread on mac (roughly ~3x, more threads don't help)
$ TLS_DOMAIN=m.jch.com RAILS_MAX_THREADS=1 WEB_CONCURRENCY=4 RAILS_ENV=production thrust bin/rails server
$ wrk -t10 -c100 -d30s https://m.jch.app
Running 30s test @ https://m.jch.app
  10 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
     Latency    29.96ms  128.94ms   1.92s    98.38%
     Req/Sec    46.60     36.89   220.00     71.97%
  8074 requests in 30.10s, 148.47MB read
  Socket errors: connect 0, read 0, write 0, timeout 814
Requests/sec:    268.21
Transfer/sec:      4.93MB

I thought the battery would be a nice UPS in case of a power outage, but it's completely shot. I realized this one day when our robovac bumped the power adapter loose and the site went down. No plans to replace the battery because this generation of laptop required replacing the entire top case (keyboard / battery).

$ pmset -g batt | grep -v "drawing from 'AC Power'" && osascript -e 'tell application "Messages" to send "Ack! Powers out" to buddy "jollyjerry@gmail.com"'

Access development server from phone or other devices for testing. These are part of bin/setup

# Jerrys-MacBook-Pro, accessible at Jerrys-MacBook-Pro.local via mDNS
scutil --get LocalHostName
scutil --set LocalHostName roboplan-dev  # roboplan-dev.local

# Firewall configuration, still bit wonky
sudo codesign --force --sign - $(which ruby)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which ruby)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

# Test firewall and dns
ruby -run -e httpd . -p 3000
curl http://localhost:3000
curl http://$(ifconfig | grep 192 | awk '{print $2}'):3000
curl http://roboplan-dev.local:3000

# config/development.rb
config.hosts << `scutil --get LocalHostName`.strip + '.local'

Thank you for stopping by and reading, and I hope you this inspires you to save some old hardware too.

In my app, users can enter a financial independence goal and their annual expenses. These numbers can be thousands or millions, so it's more readable to have a currency symbol and some separators. My goals are:

• Form submits a numeric value
• Cursor doesn't jump around when user is editing the value
• Preview a formatted currency

<input type="number" /> has built-in browser validation and a numeric keyboard on mobile. The step controls make sense if you want to make it easy for users to go up or down by $1 or $0.01, but different people have very different FI numbers and annual expenses.

From the MDN docs:

The number input type should only be used for incremental numbers, especially when spinbutton incrementing and decrementing are helpful to user experience. The number input type is not appropriate for values that happen to only consist of numbers but aren't strictly speaking a number, such as postal codes in many countries or credit card numbers.

<input type="text" inputmode="decimal /> still gives a numeric keyboard on mobile, but skips the step controls. I started with this, but ran into readability issues for bigger numbers.

A donation site might have buttons for $5, $10, $20, $100, and a custom donation amount. This makes sense if you want to anchor a user to some suggested value. It's also helpful if it helps users do some calculation like a percentage based tip. I thought about making a default like $1MM for an FI goal, but again, I didn't think it was better to have a default value.

There are a lot of libraries that format currency as a user types (see notes). React seems the most popular at the moment (2024), but there are posts for jQuery from a decade ago. Looking at the source for these libraries was helpful:

• Setting an input's value resets it's cursor position to the end
• Attempts to maintain cursor position programmatically while formatting the same text is complex, buggy, and brittle

Banking apps have the best implementation of this approach. To prevent the cursor jumping around while editing, they force the cursor to the beginning or the end.

Bank of America starts the cursor at the end. As you enter numbers, the cursor stays at the end and fills in each digit from right to left ($0.01 $0.12 $1.23 $12.34) Weirdly, it also lets you move the cursor to the front, but it jumps back to the end when you enter a number ($0.00, enter a 2 gives you $20.00 and the cursor is at the end again.)

Paypal's approach feels more intuitive. It starts the cursor at the beginning ($), adding commas as you type left to right ($1 $12 $123 $1,234). It forbids you from moving the cursor to change the middle. You have to delete to go back, and it updates any separators as you edit.

While I like PayPal's experience in a native context, I don't want to fight the browser and try to override the cursor position.

A variant to masking with a formatted value, separating the visual formatted value from the input's number value simplifies the implementation, but isn't as intuitive for user experience. My favorite example of this is in spreadsheets. A cell with a numeric value can be formatted in different ways, but the underlying value is still a number. When you edit the cell, there are no separators. Only when you finish editing (cell loses focus), does the value get formatted.

Here's one implementation that does this, but reusing the same form control means that the server has to parse the formatted value back to a number. The React component kept separate state for the formatted value and the raw number value.

<label>
  <p>Try entering some long and short numbers...</p>
  <input class="currency" inputmode="decimal" type="text" value="1234.56" style="padding: 0.5em; font-size: 1.2em">
</label>

<script id="currencyJs" type="module">
  const iso_4217 = {
    'en-US': 'USD',
    'en-GB': 'GBP',
    'de-DE': 'EUR',
    'fr-FR': 'EUR',
    'es-ES': 'EUR',
    'it-IT': 'EUR',
    'ja-JP': 'JPY',
    'zh-CN': 'CNY',
    'ko-KR': 'KRW',
    'ru-RU': 'RUB',
    'ar-SA': 'SAR',
    'hi-IN': 'INR',
    'pt-BR': 'BRL',
    'tr-TR': 'TRY',
    'nl-NL': 'EUR',
    'pl-PL': 'PLN',
    'th-TH': 'THB',
    'vi-VN': 'VND',
    'id-ID': 'IDR',
    'ms-MY': 'MYR',
  };

  const CurrencyInput = class {
    constructor(element) {
      this.element = element;
      this.locale = navigator.language || navigator.userLanguage || 'en-US';
      this.element.addEventListener('blur', this.format.bind(this));
      this.element.addEventListener('focus', this.unformat.bind(this));
      this.format();
    }

    get formatter() {
      return new Intl.NumberFormat(this.locale, {
        style: "currency",
        currency: iso_4217[this.locale] || 'USD',
      });
    }

    format() {
      this.raw = this.element.value;

      if (!isNaN(this.element.value)) {
        this.element.value = this.formatter.format(this.element.value);
      }
    }

    unformat() {
      this.element.value = this.raw;
    }
  };

  new CurrencyInput(document.querySelector('.currency'));
</script>

To submit a number and display a formatted value, I create a 2nd input element and toggle the visibility on focus and blur. The formatted input does not have a name attribute, so it is not submitted with the form, while the original input keeps the number value. This is more complex, but keeps the changes localized at the input element so the form does not need to be aware. It's also a progressive enhancement of the original input, allowing it to work without javascript.

The separation of the numeric value for form submission from visual presentation is key. Trying to maintain the state of both through input.value isn’t sufficient. React has a advantage here for managing state, and I'm following a simliar pattern by maintaining the number state and formatted state in the DOM.

Similar to the approach detailed in the notes, I format as a currency when an input loses focus, and switch back to the raw value when the input is being edited. The increased complexity of maintaining cursor position was not worth the improvement in user experience.

• navigator.language is widely available for locale information
• ISO 4217 defines currency codes by locale
• Intl.NumberFormat and Number.prototype.toLocaleString can format numbers as locale-aware currencies
• https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#concept-textarea/input-selection cursor position on input update
• Why not use a number input type? https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number#using_number_inputs
• Format onblur, use real value when editing: https://levelup.gitconnected.com/creating-a-localized-currency-input-in-react-without-libraries-or-bugs-2f186124aedc?gi=b8408a661baa
• Cursor position arithmetic, too complex to maintain: https://stackoverflow.com/a/39279790
• https://github.com/toarm/number-format?tab=readme-ov-file web component for display, but not an extension on input
• https://github.com/IngressoRapidoWebComponents/money-input?tab=readme-ov-file web component on input, has cursor position issue
• https://devtoolstips.org/tips/en/inspect-user-agent-dom/
• Forcing input cursor to the end: https://stackoverflow.com/questions/511088/use-javascript-to-place-cursor-at-end-of-text-in-text-input-element
• Replacing the input’s value on change puts the cursor at the end of the input, while using setRangeText gives more control over where the cursor lands. Attempts to solve this programmatically with arithmetic on input.selectionStart and input.selectionEnd are brittle.

The intuitive turbo lifecycle callback to fix this would be to customize turbo:before-render. However, that's too late in the lifecycle. Instead, the fix was to conditionally disable view transitions on swipe gesture navigation by removing the view-transition meta tag in turbo:before-cache. Source and demo up at https://jch.github.io/turbo-cancel-view-transition/ Safari has the least friendly progressive web app experience, but I'm using it for my personal project. Hope this helps you in yours.

Back again after my earlier rant about deployments this week. I run a personal project for tracking my investments at https://jch.app. Once I was happy with the functionality, the slow page loads became annoying. I hope this random collection of notes and search keywords helps another solo dev out there.

puma: I was running out of memory on render's 512MB of ram. Given the low traffic, I cut down the workers so that it was running in standalone mode with multiple threads. slow/occasionally broken -> slow.

rack-mini-profiler: I ran this locally and in production to get a rough timing and breakdown between code and sql calls. In-memory storage of results is fine since I was testing pages I knew were slow.

propshaft / sprockets: A surprising finding from flamegraphs was that propshaft was taking a significant percentage of time in development (Dir.[]). This wasn't an issue in production since static assets were already precompiled and served outside rails, but I switched to sprockets to make it easier to compare local / prod timings. Would be an interesting problem to dig into further.

solid_cache: I used this to cache the custom sql queries I use to calculate a time series of networth (10 years of historical stock prices against my holdings). Having it cache to db keeps my infrastructure surface area small. 3+ seconds down to ~1s.

turbo frames: Lazy load the long list of assets so that it's only fetched when it comes into view. 1s -> 500ms. Breaking up the page into partials also shows how much time each partial takes with the mini_profiler, and makes the flamegraph easier to read.

ActiveRecord::QueryMethods#select: pushing some calculations to sql instead of materializing the record and doing the calculation in ruby. e.g. holdings.select``("SUM(shares * price)") 500ms -> 300ms

Increasing compute: I was hosting on render.com and increased the compute from Starter $7/mo 0.5CPU to Standard $25/mo 1CPU. Postgresql instance stayed the same at 0.5CPU. This did roughly half the request time to ~150ms. But I was curious to try out kamal and compare performance to a VPS like digital ocean. This was a good stopping point for getting to around 100-150ms page latency by mid-week. Everything after was new and for fun.

kamal / docker / digital ocean: Digital Ocean was simple enough to start a $4/mo droplet. Kamal source code is easy to walk through, and served as a starting point for what docker areas to learn about. Docker is new to me, but the documentation is good (particularly the Engine section). I ran into an issue with not being able to connect my app container to my postgres container, but that was solved after understanding how docker handles networking. tldr is to specify the IP instead of localhost from inside the container, or switch the network adapter to "network = host".

dockerfile-rails: unfortunately, I didn't run the app long enough on the vanilla rails docker file to compare, but the fly.io template have a couple memory optimizations. Would be interesting to compare the memory usage with the stock recommendations.

cloudflare: render had my origin servers behind a CDN, but since I moved to digital ocean, I configured my own here. Rails asset pipeline can be CDN aware, but I proxied the entire domain and found the default file extensions it caches to be sufficient. The only cloudflare config I had to change was to set the SSL to full to avoid redirect loop b/c traefik was rewriting all my traffic to SSL already.

deploy speed: I'm running an intel MacBook prod, so turning off multiarch under builder cut my deploy down by more than half (3min to 1min+)

Ruby, docker, registry, vm, actual hardware.

Nice that kamal and containers provide an abstraction to where you host.

All this because I didn’t want to jump to the $25/mo render plan for my personal project to boost cpu

It's all setup now at https://jch.app Even on the smallest droplet $4/mo, my heaviest page is 3-4x faster.

I made a simple system for paying bills that would follow interest rates, and reduces taxes on the earned interest.

• Use brokerage as a payment account to take advantage of high money market interest rates
• Choose tax exempt money market funds to save on taxes, especially in states with high taxes

As a California resident, Fidelity makes this easy with FDLXX:

The Adviser normally invests at least 99.5% of the fund's total assets in cash and U.S. Treasury securities. Potentially entering into reverse repurchase agreements. Normally investing in securities whose interest is exempt from state and local income taxes.

Residents in other states can find equivalents easily with a search for "tax exempt money market funds". A nice feature of this particular fund is it can auto-liquidate, meaning that payments and transfers will automatically sell this fund as needed. We do have to manually purchase this fund because it's not available as a core position. The core positions SPAXX and FZFXX also yield around ~5% currently, but my understanding is they're federal and state taxable, which would hit us with a ~22% and ~8% tax bill respectively; Eating away $300 a year in interest. There are state specific municipal bond funds that are federal and state tax exempt, but current yields net tax savings are below our marginal tax brackets. TurboTax has a checkbox to enter this information.

We're not holding additional cash to take advantage of higher yields because we are sticking with our investing strategy, but it's a nice bonus / inflation offset to earn a little on cash we need for our day-to-day expenses. This approach doesn't require chasing new account bonuses, or promotional interest rates with caveats. When rates decrease, we'll lose some interest, but it's a good set-and-forget system.

Timecop.freeze("2024/03/15") do
  assert_equal Date.current, Date.today
end

Turns out, this was documented behavior that goes way back to 2011. From the timecop README:

Sometimes Rails Date/Time methods don't play nicely with Ruby Date/Time methods. Be careful mixing Ruby Date.today with Rails Date.tomorrow / Date.yesterday as things might break.

Here are the differences between ruby's builtin Time and Date methods, compared with using ActiveSupport's TimeWithZone and Date extensions.

irb> ENV['TZ']
=> nil
irb> Time.now
=> 2024-08-15 13:48:14.639956 -0700  # no timezone set picks up system time
irb> ENV['TZ'] = 'US/Eastern'
=> "US/Eastern"
irb> Time.now
=> 2024-08-15 16:48:46.905847 -0400  # ENV['TZ'] set overrides system time

irb> require 'date'
irb> Date.today
=> #<Date: 2024-08-15 ((2460538j,0s,0n),+0s,2299161j)>

irb> Date.today.to_time
=> 2024-08-15 00:00:00 -0700

irb> require 'active_support'
irb> require 'active_support/core_ext/date/calculations'
irb> Time.zone = 'Asia/Tokyo'
=> "Asia/Tokyo"
irb> Time.now
=> 2024-08-15 13:56:27.470616 -0700  # system time!
irb> Time.zone.now
=> Fri, 16 Aug 2024 05:56:30.666951000 JST +09:00  # the following day b/c of +9 compared to my -7 system offset
irb> Date.today  # system time!
=> Thu, 15 Aug 2024
irb> Date.current  # Time.zone date
=> Fri, 16 Aug 2024

Before I figured this out, my fix for the test was to stub

Date.stubs(:current).returns(Date.parse("2024-01-01"))

Other methods have dates parameterized for testing. Since I'm not using any of timecop's travel functionality, I decided to remove the dependency.

Edit: 2024-08-28 Rails has ActiveSupport::Testing::TimeHelpers to do this without a dependency:

travel 1.day
travel_do Date.parse('2024-08-28') { ... }
freeze_time {... }
freeze_time
# ...
unfreeze_time

• Thoughtbot: It's about timezones
• Timecop PR #416: ActiveSupport Date.current differs from Date.today when Time.zone is set

class HoldingsController < ApplicationController
  def index
    session[:period] = params[:period]
  end
end

# in the navigation partial
<%= link_to "Holdings", holdings_path(period: session[:period]) %>

In my app, url path params maintains navigation state. For example, to see investment performance of holdings, there are links that look like:

/holdings              # 1 day performance by default
/holdings?period=ytd   # year to date performance
/holdings?period=all   # all time performance

This is straightforward within the Holdings#index action, but the global navigation always points to /holdings so if I navigate to another page and click on the "Holdings", it'll default back to 1 day performance instead of remembering that the user has previously selected YTD or ALL.

What's have others done to keep this state globally? What makes the most sense from a UX perspective?

Attach this as a property of current user, persist / restore across requests. This feels right to me if the state is important across different instances of the app. If I choose YTD performance on my phone, then open the app on the web, I would expect my previous choice to stick. In this sense, it feels like a global user preference that's saved across all clients.

This seems like a better abstraction than attaching it to user. If using cookie stores, users would go back to the default per client. If using database store, it'd be all clients.

Do it all client side. Per client. Persist and restore from stimulus. I like this one the least because it feels complex without additional benefit.

https://jch.app/demo is a live demo.

$ RAILS_ENV=production rake db:drop
rake aborted!
ActiveRecord::ProtectedEnvironmentError: You are attempting to run a destructive action against your 'production' database
If you are sure you want to continue, run the same command with the environment variable
DISABLE_DATABASE_ENVIRONMENT_CHECK=1

Protected environments are configurable:

# config/application.rb
ActiveRecord::Base.protected_environments << 'staging'

For older versions of Rails, I add the following to lib/tasks/db.rake:

namespace :db do
  desc 'Protect against running task in production'
  task :protect do
    fail 'Refusing to run in production environment' if Rails.env == 'production'
  end

  task :drop => :protect
  task 'schema:load' => :protect
end

My script builds upon Lyzi Diamond's post "Manage GitHub notification messages in Gmail with Google Apps Scripts".

The full API reference for Gmail is available at https://developers.google.com/apps-script/reference/gmail/.

// Main function
function processInbox() {
  var unreadThreadCount = GmailApp.getInboxUnreadCount();
  if (unreadThreadCount == 0) { return null; }

  var threads = GmailApp.getInboxThreads(0, unreadThreadCount);
  for (var i = 0; i < threads.length; i++) {
    var thread = threads[i];
    var messages = thread.getMessages();

    if ((messages[0].getFrom()).indexOf("notifications@github.com") > -1) {
      thread.moveToArchive();

      // Iterate through newest messages, returning a GmailThread if a label was added to the thread.
      // Only one label will be added, and they are listed in priority below.
      var start = Math.max(0, messages.length - 1);
      var label;
      for (var j = start; j > -1; j--) {
        var message = messages[j];
        var body = message.getRawContent();
        if (body.indexOf("X-GitHub-Reason: mention") > -1) {
          return thread.addLabel(GmailApp.getUserLabelByName("Direct mention"));
        } else if ((body.indexOf("X-GitHub-Reason: author") > -1) || (body.indexOf("X-GitHub-Reason: comment") > -1)) {
          return thread.addLabel(GmailApp.getUserLabelByName("Participating"));
        } else if (body.indexOf("X-GitHub-Reason: team_mention") > -1) {
          return thread.addLabel(GmailApp.getUserLabelByName("Team mention"));
        } else {
          return thread.addLabel(GmailApp.getUserLabelByName("Notification"));
        }
      }
    }
  }
}

Exit early when there are no threads to process

This fixes timeout and resource exhaustion errors. Google has limits on how much resources a script can take per run.

Apply label by priority

Rather than matching every GitHub header, this script applies the most important label to a thread. I check my messages in this order:

• Direct Mention
• Partcipating
• Team mention
• Notification

This script assumes "Direct Mention", "Participating", "Team mention", and "Notification" labels exist. Labels can be created programmatically, but I decided it was not worthwhile for such a simple script.

Process newest messages first

By processing newest messages first, threads will always have the highest priority label applied. This is also good for performance because the script stops processing a thread as soon as we label one of it's messages.

Archive notification emails only

Other GitHub emails should still pass through.

The latest version does even less processing to reduce time outs.

// Modified from http://lyzidiamond.com/posts/github-notifications-google-script/

// Assumes incoming threads from notifications@github.com are labeled with `unprocessed`.

function perf(start) {
  Logger.log("Execution time: " + (Date.now() - start) + " ms");
}

function processInbox() {
  var startTime = Date.now();
  var directMentionRegexp = /@jch\b/;
  var teamRegexp = /@github\/(github|tests|other-teams)\b/;

  var unprocessedLabel = GmailApp.getUserLabelByName('unprocessed');
  var directMentionLabel = GmailApp.getUserLabelByName('Direct Mention');
  var teamMentionLabel = GmailApp.getUserLabelByName('Team mention');
  var notificationLabel = GmailApp.getUserLabelByName("Notification");

  var threads = GmailApp.search('label:unprocessed');

  Logger.log("Processing " + threads.length + " threads");

  for (var i = 0; i < threads.length; i++) {
    // Remove the `unprocessed` label, it'll be re-labeled again if a new message comes in
    var thread = threads[i];
    thread.removeLabel(unprocessedLabel);

    // Thread is already labeled, no need to process further
    var labels = thread.getLabels();
    if (labels.includes(directMentionLabel) || labels.includes(teamMentionLabel)) {
      continue;
    }

    // Iterate through newest messages, exiting if a label was added to the thread.
    // Only one label will be added, and they are listed in priority below.
    var messages = thread.getMessages();
    var start = Math.max(0, messages.length - 1);
    var label;
    for (var j = start; j > -1; j--) {
      var message = messages[j];

      if (!message.isUnread()) {
        break; // remaining messages have been processed before
      }

      var body = message.getPlainBody();
      if (directMentionRegexp.test(body)) {
        thread.addLabel(directMentionLabel);
        break;
      } else if (teamRegexp.test(body)) {
        thread.addLabel(teamMentionLabel);
        break;
      } else {
        thread.addLabel(notificationLabel);
      }
    }
    perf(startTime);
  }

  perf(startTime);
}

Although we meet regularly, here are a few things I do to make the most of these meetings.

Before each meeting, I spend roughly 15 minutes preparing a simple bullet point list of topics I want to cover. This agenda gives Dave a preview, and a chance to gather relevant information. It's also useful during the meeting as an outline. I usually include:

• a review last week's meeting
• high level accomplishments
• recognition for team members that are doing a great job
• questions
• reminders about upcoming events

I like to jot down notes as we talk. I write down things I find useful or want to think about after the meeting. Some examples include feedback about ways I can improve, feedback about how my manager could make my project run smoother, and things that are happening outside of my project that's relevant to my interests. It's a good time to discover new projects and opportunities. I find that the agenda will often trigger us to share bits of useful information that would've otherwise gone unmentioned.

Before we end a meeting, we talk about things that need follow up. It could be an idea that needs more research, or it could be coordinating schedules for a team offsite. Whatever these may be, we decide who is responsible, and when it needs to be done.

After each meeting, I dump my notes into a email reply for review at the following meeting. Dedicated review time is great because we know we'll revisit things the following week, so there's no need to waste brain cycles worrying during the week.

Dave and I have gotten to know each other better through these one on ones. Even with an agenda, they feel casual and easy going. We live in different cities, so most of our meetings happen over video chat, but when we are in the same place, we like to do go for a walk or have a chat over coffee.

Learning about the other person's goals and background subtly shapes our interactions. Over time, we build up our trust in each other, and become more effective in our day to day work. We get a better sense of the other person's communication styles, and also what they're looking for.

It's easy to take one on ones for granted. But with some attention and care, effective one on ones are a great tool for your career. Agendas and notes keeps everyone focused, while review and follow up prevents things from being forgotten or neglected. Over time, these meetings become an open and safe place to talk about long term goals.

Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface. -Doug McIlroy, Inventor of Unix pipe

This post illustrates some of the ideas behind the Unix philosophy by composing utilities together to convert Markdown to HTML. I chose Ruby because it's a language I'm familiar with, but also to show that shell scripting does not require bash. The main idea is to write small filter scripts that can be composed together with pipes to create flexible tools.

Typically, Ruby files end with a .rb extension and are executed by invoking the Ruby interpreter explicitly. But instead typing out ruby markdown.rb each time, we can use a shebang at the top of our script to indicate which language and interpreter to use.

#/usr/bin/env ruby
# This first line allows us to name our script `markdown` without the .rb extension

To skip invoking ruby explicitly, use a terminal to change the permission of our script to make it executable:

$ chmod +x markdown
$ ./markdown  # no output and no errors

For the first iteration, our script will take a single argument -- a filename of a markdown document to convert to html. Command line arguments are available through an Array named ARGV.

#/usr/bin/env ruby
markdown_file = ARGV.first # ARGV is ['foo.md']
puts markdown_file

If we run our script, we see that ARGV is whatever arguments we pass in:

$ ./markdown foo.md
foo.md

Other languages sometimes provide a convenience method named ARGC to indicate the number of command line arguments ((ARG)ument (C)ount) , but since ARGV is an array, it's easy to grab the number of arguments by calling ARGV.length.

For a simple script like ours, it's sufficient to work with ARGV directly. If there are complex options and flags to parse, the standard library's optparse module is a good starting point. This gist is a template and an example for parsing conventional POSIX style flags.

We have a markdown filename. The next step is to convert it to HTML. There are many gems that will accomplish this, but for the sake of the exercise, we don't install any gems. Instead, we can use GitHub's markdown API with curl. For example:

$ echo '{"text": "# header"}' | curl -s -H 'Content-Type: text/plain' https://api.github.com/markdown -d'@-'

The first half of the pipeline uses echo to print a JSON snippet to stdout. We pipe this output to curl. The last argument -d'@-' is how we send the stdin data to GitHub. From curl's man page:

-d, --data If you start the data with the letter @, the rest should be a file name to read the data from, or - if you want curl to read the data from stdin.

-s makes curl's output less noisy, and -H lets us pass in custom HTTP headers required by the API.

Our script's immediate goal is to produce JSON similar to the echo command in our example above. Again, we do not need an external library because json is available through the standard library:

#/usr/bin/env ruby
require "json"

markdown_file = ARGV.first
payload = { :text => File.read(markdown_file) }.to_json

puts payload

We can test this works as expected by executing:

$ echo "# header" > foo.md
$ ./markdown foo.md | curl -s -H 'Content-Type: text/plain' https://api.github.com/markdown -d'@-'
<h1>header</h1>

With our prepared JSON payload, our next step is to handle the pipe within our script. Ruby's IO.pipe is a general way of creating a connected read and write pipes, but for our purposes, we're interested in the higher abstraction of the open3 module:

#/usr/bin/env ruby
require "json"
require "open3"

markdown_file = ARGV.first
payload = { :text => File.read(markdown_file) }.to_json

curl_cmd = %Q(curl -s -H 'Content-Type: text/plain' https://api.github.com/markdown -d'@-')

# `stdin`, `stdout`, `stderr` are the respective file handlers for the curl command
stdin, stdout, stderr = Open3.popen3(curl_cmd)

# Take the json we built and give it to curl via it's stdin. We have to
# explicitly close it's stdin before we can access it's stdout. Otherwise, curl
# will keep waiting for more input.
stdin.puts payload
stdin.close

# Print out curl's output to stdout and stderr
puts stdout.read
$stderr.puts stderr.read

Let's try it out:

$ echo "# header" > foo.md
$ ./markdown foo.md
<h1>header</h1>

In our last example, we had to create a markdown file because our script expects a filename as an argument. The great thing about most Unix utilities is they default to operating on stdin and stdout. This makes it easy to chain commands together so that the stdout of one command flows into the stdin of the next. For example, both of the following commands will print the number of lines in a file:

# count the number of lines for a given filename
$ wc -l README.md

# print out the file, then count the number of the lines on stdin
$ cat README.md | wc -l

We can improve our markdown script with this behavior; Convert a file if a file name is given, or convert whatever is passed in via stdin if there are no arguments.

#/usr/bin/env ruby
require "json"

markdown_file = ARGV.first
markdown_content = markdown_file ? File.read(markdown_file) : $stdin.read
payload = { :text => markdown_content }.to_json

# snip

We can simplify this code further by using Ruby's ARGF object. From the docs:

ARGF is a stream designed for use in scripts that process files given as command-line arguments or passed in via STDIN.

The same code rewritten with ARGF would look like:

#/usr/bin/env ruby
require "json"

markdown_content = ARGF.read
payload = { :text => markdown_content }.to_json

# snip

As an added bonus, ARGF works on multiple filenames, allowing our script to process multiple files at once:

# ARGF.read will read in all 3 files
$ ./markdown foo.md bar.md baz.md

The complement to processing stdin by default is to keep stdout on topic. Stdout should be reserved only for the intent of the original script. In our script, the only output should be HTML because the script is used to convert markdown to HTML. We avoid logging diagnostic messages or printing progress counters unless we decide to add flags to our script that support these features. This allows us to easily chain more commands after our own script. For example, if we want to indent the output from our command, we can use the tidy command and know that everything we output is HTML:

$ ./markdown.sh foo.md | tidy -i

Script exit codes allow us to control the flow of our pipelines. For example, we may want to publish the results of running markdown, but only if the command succeeded:

# Generate blog-post.html. If successful, run `./publish`, otherwise, print an error message
cat blog-post.md \
  | ./markdown > blog-post.html && ./publish || echo "failed to publish blog-post.html"

A successful exit is 0, with any other number indicating something went wrong. Unfortunately, if we ran the above, we would always publish and never see the error message even if curl failed. Our script doesn't call exit explicitly, so we always exit 0 -- even when GitHub's API isn't accessible.

Since the last thing our script run is curl, our script should exit with curl's exit code. Our current call to Open3.popen3 saves three of the return values, but the method actually returns four. We will use this fourth value to query for curl's exit code.

# snip

# We add a -f flag so that non-200 responses fail with an exit code of 22
curl_cmd = %Q(curl -f -s -H 'Content-Type: text/plain' https://api.github.com/markdown -d'@-')

# `stdin`, `stdout`, `stderr` are the respective file handlers for the curl command
# `thread` is a `Thread` instance representing the command we're running
stdin, stdout, stderr, thread = Open3.popen3(curl_cmd)

# snip

# thread.value is a `Process::Status`. We exit our script with whatever curl's
# exit code was.
exit thread.value.exitstatus

By following these simple conventions, our scripts work well with other existing Unix tools. This allows us to quickly prototype things that would otherwise require a lot of setup and dependencies. Since the scripts aim to handle a single task, we are more likely to reuse the script for tasks that we didn't original intend for the script to handle.

Our final source listing is:

#/usr/bin/env ruby
require "json"
require "open3"

markdown_file = ARGV.first
payload = { :text => File.read(markdown_file) }.to_json

# Curl command to post STDIN to GitHub's markdown API
#
# -f: non-200 responses fail with an exit code of 22
# -s: silent
# -H: http headers
curl_cmd = %Q(curl -f -s -H 'Content-Type: text/plain' https://api.github.com/markdown -d'@-')

# `stdin`, `stdout`, `stderr` are the respective file handlers for the curl command
# `thread` is a `Thread` instance representing the command we're running
stdin, stdout, stderr, thread = Open3.popen3(curl_cmd)

# Take the json we built and give it to curl via it's stdin. We have to
# explicitly close it's stdin before we can access it's stdout. Otherwise, curl
# will keep waiting for more input.
stdin.puts payload
stdin.close

# Print out curl's output to stdout and stderr
puts stdout.read
$stderr.puts stderr.read

# thread.value is a `Process::Status`. We exit our script with whatever curl's
# exit code was.
exit thread.value.exitstatus

I use this to generate the markup for this blog. The full source is available at jch/jsg.

protected_app = Rack::Auth::Basic.new(Resque::Server) do |username, password|
  password == 'some-secret'
end

# mount protected_app in Rails, or other rack application…

This kind of works, but I always forget the password and have to look it up. It also sucks for on boarding new developers since it's not very discoverable. An improved solution is to piggyback onto your existing authentication system. For one of our apps, we use Devise, which exposes the user object in the Rack env object. Roughly, our rescue authentication looks like:

# config/initializers/resque.rb
class AuthenticatedMiddleware
  def initialize(app)
    @app = app
  end

  def call(env)
    if env['warden'].authenticated? && env['warden'].user.staff?
      @app.call(env)
    else
      [403, {'Content-Type' => 'text/plain'}, ['Authenticate first']]
    end
  end
end

Resque::Server.use(AuthenticatedMiddleware)

# config/routes.rb
mount Resque::Server, :at => '/resque'

If the main application is a Rails app, you can also use routing constraints to limit access. The benefit here is the Rail request and session object are available. For example, in another internal-only application, we only check that the session includes a user id:

# config/routes.rb
class SessionAuthenticatedConstraint
  def self.matches?(request)
    !request.session[:user_id].blank?
  end
end

constraints(SessionAuthenticatedConstraint) do
  mount Resque::Server, :at => '/resque'
end

Overall, I prefer the last approach because it's easy to understand, easy to test, idiomatic of Rails conventions, and short.

Shout outs to @kdaigle for code reviewing me and suggesting the last approach, and @jonmagic for reviewing this post.

Every time we bring in an external library, we inherit its opinions, shortcomings, idioms, and taste. This isn't a reason to rewrite everything ourselves, but it's good for us to interview libraries like we interview new GitHubbers.

I loved this. In two short sentences, Barnette summed up why we should evaluate new dependencies before adding them to an existing project.

It's tempting to add a library that promises to do 90% of your goal. But that instant gratification often comes with delayed hidden costs. Things I've been bitten by in the past include:

• Security. It's hard, and no one gets it right the first time.
• Performance. Sure it works in the simple case, but does it scale?
• Complexity. It's not worth importing a kitchen sink if you're only planning to use one small method.
• Lack of benefit. Some libraries just don't buy you very much. Syntactic sugar is nice if it wraps an ugly interface, but if it doesn't, it means keeping two interfaces in you head while you work.
• Organizational cost. Does your team know how to use it? If not, is it worth it for them to pick it up? It's better to choose something plainer, simpler, and more explicit if it means the rest of your team can easily understand and work with it.

I've worked with Rails for a long time now, and I have a good sense of where to poke around if I have questions. But let's be honest, with 183 commits made by 63 authors in the last week alone, I'll never know Rails inside and out.

Rails is large and complex. Yet, I'm happy to use it daily in my project. Why? Because I trust the project and community to stick around. It'd be a pain to rewrite what Rails buys you. Plus, the documentation is great, there are timely security patches, and my team knows how to use it.

None of the hidden costs I listed above are hard rules for rejecting a library. But the next time you think about adding a library to your codebase, grill it with some hard questions and see if it's worth adding.

The first time you think of encodings in Ruby is probably the first time you see an exception along the lines of:

incompatible character encodings: ASCII-8BIT and UTF-8

Before you pull out your hair, I recommend reading James Edward Grey II's in depth coverage on why and what encodings are. Markus Prinz's Working with Encodings in Ruby 1.9 is also a good read. Go ahead, this article will wait.

The core cause of the above error is when your code tries to mash two strings with different encodings together. For example, trying to glue a UTF-8 Chinese string to an ASCII-8BIT English string. They're hard to hunt down because the error is generated in C code and doesn't descend from the Exception class. This means you can't rescue the error to inspect it. Your best tool for finding the origin of the error is to learn about the Encoding module. Once you're familiar with that API, it's easy to inspect the encoding to check it's what you expected.

"some string".encoding
"some string".force_encoding('UTF-8')

Rails defaults to UTF-8 for encoding. You can change it via application.rb with:

config.encoding = 'UTF-8'

Yehuda Katz has a good write up describing the problem. The long term solution is to have libraries that deal with external strings to respect Encoding.default_internal

To make sure your database uses the correct encoding, set your connection adapter to the correct encoding:

# config/database.yml
development:
  encoding: unicode

When template views are read in from the filesystem, it respects the global ruby default for encoding. This can be overridden by a special shebang-like declaration at the top of the file:

# encoding: utf-8

Check out ActionView::Template#encode! for more details.

If you're seeing an incompatible encoding error in a view, it's possible that it's caused by rendering a value from an external gem or string. Remember that the render method returns a string. A quick way to inspect that your partials are in the correct encoding is to save the result of a partial into a variable and print it's encoding:

<% output = render(:partial => 'some/partial') %>
<%= output.encoding %>

Don't [forget to set your environment variable](http://stackoverflow.com/questions/7612912/set-utf-8-as-default- string-encoding-in-heroku) to the correct default encoding.

$ heroku config:add LANG=en_US.UTF-8

Rack [was released in 2007](http://chneukirchen.org/blog/archive/2007/02 /introducing-rack.html) by Christian Neukirchen. The project README starts with:

Rack provides a minimal, modular and adaptable interface for developing web applications in Ruby. By wrapping HTTP requests and responses in the simplest way possible, it unifies and distills the API for web servers, web frameworks, and software in between (the so-called middleware) into a single method call.

Confused? Don't worry, we'll go over each part individually.

By wrapping HTTP requests and responses in the simplest way possible...

Stepping back from Ruby, what is the 'simplest way' to think about an HTTP request and response? Without knowing the language or framework an application is using, the perspective from a webapp looks like:

HTTP Request -> Webapp -> HTTP Response

An HTTP request has a method like GET or POST, a server host and port, some uri resource path, and optionally a query string.

GET /posts?page=2     # method, resource uri, query string
Accept: 'text/html'   # one or more HTTP headers...
Cookie: 'foo=bar'
X-Custom: 'value'

The web application's job is to takes this information and generate a HTTP response like:

200 OK
Content-Type: 'text/html'
Content-Length: 75
<html>
  <body>Hello!</body>
</html>

Without knowing how the response was generated, the parts of an HTTP response are the same independent of language and framework. The 200 status code indicates a successful response. Additionally, HTTP header fields describe what the response is.

Rack wraps the request and response information into one large hash called the environment hash. Rack passes this env hash to your application and expects a return value with 3 parts:

• status - an HTTP status code
• headers - a hash of response headers. e.g. Content-Type, Content-Length
• bodies - an array-like object that responds to #each and yields strings of response content

[rack] unifies and distills the API for web servers, web frameworks ... into a single method call

The only entry point that a Rack component must implement is a method named #call that takes the env hash as its only argument. For example, the following is a valid Rack application:

class MyApp
  def call(env)
    # env has request/response information
    puts env['PATH_INFO']
    puts env['HTTP_ACCEPT']

    # return status, headers, and response bodies.
    # note that multiple response bodies will be concatenated.
    [200, {'Content-Type' => 'text/html'}, ['Hello!']]
  end
end

As an application developer, you can think in terms of the env hash instead of parsing out all the HTTP values manually. The response MyApp generates is returned in the last line as an array, and has the status code, headers, and list of response bodies.

Rack also provides an object-oriented interface to access request information and building responses. MyApp can also be written as:

class MyApp
  def call(env)
    request  = Rack::Request.new(env)
    request.get?     # is the request a GET request?
    request.params   # query parameters
    request.cookies  # yummy

    # do stuff with `request`...

    response = Rack::Response.new
    response['Content-Type'] = 'text/html'
    response.write 'Hello!'

    response.finish  # converts object into rack expected response
  end
end

We say something is rackable when it responds to a method #call that takes one argument (the env hash), and returns a rack compatible response. For really simple Rack components, a common shortcut is to use a [lambda](http://www.robertsosinski.com/2008/12/21/understanding-ruby-blocks- procs-and-lambdas/) to define an anonymous endpoint. Because lambdas and procs respond to #call, it fits the Rack requirement.

lambda {|env|
  [200, {'Content-Type' => 'text/plain'}, ['This is a valid rack app']]
}

See the documentation for Rack::Request and Rack::Response for details. The Rack specification has a full listing of what's available in the environment hash.

Now that we've seen what Rack is, let's explore the benefits from implementing this contract.

An application server is a library responsible for handling the plumbing of HTTP. It takes care of things like binding to a port, listening for connections, parsing headers, and constructing responses. Sometimes they are a collection of tools each responsible for one part of serving a HTTP request, other times, they may be one monolithic tool that handles all parts of the HTTP lifecycle. Each app server has different features, allowing you to choose one that's right for your needs.

Rack makes it easy to switch between app servers without touching your application code. For example, to serve our sample application with the builtin Ruby HTTP server WEBrick:

require 'rack'

class MyApp
  def call(env)
    [200, {'Content-Type' => 'text/html'}, ['hello']]
  end
end

Rack::Handler::WEBrick.run(MyApp.new, {:Port => 3000})

If you wanted to use a different app server, for example Thin, then you can change the last line to:

Rack::Handler::Thin.run(MyApp.new, {:Port => 3000})

Both of the above files can be directly run from the command line. See the Rack::Handler documentation for details.

Rack middleware is a Rack component that manipulates the environment hash before invoking another Rack component's #call method. Middleware can be used to modify a request before an application sees it, or modify a response generated by an application. This is useful for building shared filters that are independent of the underlying application. For example, to filter the word 'truck' from all response bodies:

class ProfanityFilter
  # Middleware need to accept a downstream Rack component
  def initialize(app)
    @app = app
  end

  def call(env)
    # call underlying application, returning the standard rack response
    # @app is always initialized as the `next` rack component to call
    status, headers, bodies = @app.call(env)

    # modify response bodies in place
    bodies.map! {|body| body.gsub! /truck/, ''}

    # return a valid rack response
    [status, headers, bodies]
  end
end

This middleware is an example of a middleware that modifies the response generated by a downstream application. Like other Rack components, it also uses #call as it's entry point. In addition to this, its first constructor argument has to be another Rack component. The convention is to save this argument in an instance variable called @app. Middleware can determine when it wants to call the downstream app, and what to do with the app's response.

By having this stackable chain of middleware components feeding into each other and manipulating each others' inputs and responses, it makes it possible to compose application behavior in separate reusable components rather than a single fat blob of code.

Rack comes builtin with a utility object for composing middlewares and applications together called Rack::Builder. For example the following wraps the ProfanityFilter middleware around the MyApp application:

app = Rack::Builder.new do
  use ProfanityFilter
  run MyApp
end

Rack::Handler::WEBrick.run(MyApp.new, {:Port => 3000})

To further remove boilerplate code, Rack comes with a convenience executable called rackup that allows you to swap out servers without any code. When run without arguments, rackup looks for a file named config.ru to configure a Rack::Builder instance:

# sample 'config.ru' evaluated within a Rack::Builder instance
use ProfanityFilter
run MyApp

Then to run the application from the commandline:

> rackup config.ru
> rackup -s thin -p 4000  # use thin as a server and run on port 4000

Any additional arguments passed to use will be passed to the contructor of the middleware. Remember that the first argument of a middleware is always the downstream Rack component:

# extra arguments are passed into the middleware constructor
use Rack::Session::Cookie, :key => 'rack.session'

Multiple Rack components can manipulate the environment hash serially without knowing what other rack components are being used. Each component run after the last, and its own response is passed back to the component above it. Sometimes a middleware will inject additional functionality into the environment hash for downstream components to use. One example is Rack::Session::Cookie, a middleware that adds a env['rack.session'] object for downstream apps to use.

use Rack::Session::Cookie

run lambda {|env|
  # Rather than manipulating cookies ourselves, the upstream middleware gave
  # us a helper object to set and read cookies

  puts env['rack.session']  # read what's in our session
  env['rack.session']['some_key'] = 'some_value'  # written to cookie for us
}

Because the environment hash is a plain old Ruby hash, you can decorate it with any functionality you want. Typically the convention is to use string keys and to namespace the key by the project name. For example, OmniAuth is a Rack library that allows applications to plugin different authentication providers. When authentication completes, the relevant auth information is given in an env['omniauth.auth'] hash. The values don't have to be Ruby primitive objects either. In Rack::Stream, a library for building streaming Ruby webapps, env['stream.app'] is a Rack::Stream::App instance that has callable methods and features that can be used downstream. The contract of what's made available downstream is up to individual libraries, but the separate between each layer helps keep the components separate and well factored.

Rails is one of the best examples of a complex chain of middleware in action. In fact, if you generate a bare Rails app, and run rake middleware, you'll see:

> rake middleware

use ActionDispatch::Static
use Rack::Lock
use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x007f8424bd1a50>
use Rack::Runtime
use Rack::MethodOverride
use ActionDispatch::RequestId
use Rails::Rack::Logger
use ActionDispatch::ShowExceptions
use ActionDispatch::DebugExceptions
use ActionDispatch::RemoteIp
use ActionDispatch::Reloader
use ActionDispatch::Callbacks
use ActiveRecord::ConnectionAdapters::ConnectionManagement
use ActiveRecord::QueryCache
use ActionDispatch::Cookies
use ActionDispatch::Session::CookieStore
use ActionDispatch::Flash
use ActionDispatch::ParamsParser
use ActionDispatch::Head
use Rack::ConditionalGet
use Rack::ETag
use ActionDispatch::BestStandardsSupport
run MyApp::Application.routes

Each item in this list processes an incoming environment hash and calls the Rack component under it in turn. What do all these entries have in common? They all respond to #call, and they all follow the Rack specification.

The final entry, MyApp::Application.routes, is the routes defined by config/routes.rb and is an ActionDispatch::Routing::RouteSet object that maps path info to controller actions. Each Rails controller action is a Rack endpoint in itself. You can verify this by running the following in a rails console:

# assuming a controller named `MyController` with an `index` action:
> rails console
> MyController.action(:show)
#<Proc:0x007ff1ed33bfd0@/Users/jch/.rvm/gems/ruby-1.9.3-p194/gems/actionpack-3.2.6/lib/action_controller/metal.rb:245>

You can see that fetching an action by name returns a Proc object, which responds to #call.

For additional Rails specific tips and information on Rack, check out the Rails guide Rails on Rack.

• Rack::Test - test rack middleware and apps. Used by other test frameworks.
• Rack::Cache - one of my favorites. Teaches you how HTTP caching works, and a very useful middleware. Also checkout [activesupport-cascadestore](https://github.com/jch /activesupport-cascadestore).
• Rack::Cors - cross origin resource sharing. Lets you do cross-domain ajax
• Rack::Profile - use ruby's profiler to see what's slow
• rack-contrib - whole bunch of useful middlewares
• Rack::Recaptcha
• Rack::Rewrite - rewrite incoming urls
• Ruby Toolbox Rack Projects

• [Introducing Rack](http://chneukirchen.org/blog/archive/2007/02 /introducing-rack.html) - rack's author Christian Neukirchen explains the rationale behind writing rack.
• Railscasts has a Rack Middleware screencast.
• Rails on Rack

In the earliest days of this blog, I think I was more interested in writing a blogging system than actually blogging. The original code that generated this site were a kludgey set of Perl scripts that stitched together markdown content into HTML. It's fun to read my rationale behind building a blog engine, but in reality, it was a mistake to build something from scratch rather than to extend an existing system. Now I'm stuck with it, but at least the latest version is a lot tidier and more maintainable than my earlier attempts.

I laughed at how stupid most of my earlier posts sound, but this post on premature testing stood out as one of the few posts that still feel relevant today. In the same vein of overtesting, I also really enjoyed DHH's post Testing like the TSA.

I've enjoyed and learned a lot at each place I've worked at. I still keep in touch with ex-coworkers, and have met some of my closest friends through work. While I don't have blog posts going all the way back, it was fun to read posts for when I started at a new workplace.

• Coupa and Rails 2
• Starting my own Company Outspokes
• New Beginnings: Starting with Intridea

While my technical skills have improved since those early posts, I still have much to learn. I'm happy that I'm just as excited to design and program today as I was when I first started. If anything, the past projects and problems I've tackled have opened up a whole new realm of challenges for me to take on. I'm excited to see where I'll go next - both as a developer, and as an individual.

A Rails controller is a subclass of ActionController::Base. The documentation says:

Action Controllers are the core of a web request in Rails. They are made up of one or more actions that are executed on request and then either render a template or redirect to another action. An action is defined as a public method on the controller, which will automatically be made accessible to the web-server through Rails Routes.

While Base suggests that this is a root class, it actually inherits from ActionController::Metal and AbstractController::Base. Also, some of the core features such as rendering and redirection are actually mixins. Visually, this class hierarchy looks something like:

ActionController::Metal is a stripped down version of what we know as controllers. It's a rackable object that understands HTTP. By default though, it doesn't have know anything about rendering, redirection, or route paths.

AbstractController::Base is one layer above Metal. This class dispatches calls to known actions and knows about a generic response body. An AbstractController::Base doesn't assume it's being used in an HTTP request context. In fact, if we peek at the source code for actionmailer, we'll see that it's a subclass of AbstractController::Base, but used in the context of generating emails rather than processing HTTP requests.

module ActionMailer
  class Base < AbstractController::Base
    include AbstractController::Logger
    include AbstractController::Rendering  # <- ActionController::Base also uses
    include AbstractController::Layouts    # <- these mixins, but for generating
    include AbstractController::Helpers    # <- HTTP response bodies, instead of email response bodies
    include AbstractController::Translation
    include AbstractController::AssetPaths
  end
end

For a recent project, I needed to execute flight searches in background jobs against an external API. Initially, I planned to push the search results as a json object and render everything client-side, but I wanted to reuse existing Rails views, helpers, and route path helpers without redefining them in the frontend. Also, because of differing client performance, rendering server-side improves page load times for users in this instance. Architecturally, what I wanted looks like:

The requirements for this custom controller were:

• access to route helpers
• renders templates and partials in app/views

Unlike a full blown ActionController, this custom controller doesn't need to understand HTTP. All it needs is the result of the flight search from background workers to be able to render an html response.

The full code for the custom controller is:

class SearchRenderer < AbstractController::Base
  include Rails.application.routes.url_helpers  # rails route helpers
  include Rails.application.helpers             # rails helpers under app/helpers

  # Add rendering mixins
  include AbstractController::Rendering
  include AbstractController::Logger

  # Setup templates and partials search path
  append_view_path "#{Rails.root}/app/views"

  # Instance variables are available in the views,
  # so we save the variables we want to access in the views
  def initialize(search_results)
    @search_results = search_results
  end

  # running this action will render 'app/views/search_renderer/foo.html.erb'
  # with @search_results, and route helpers available in the views.
  def execute
    render :action => 'foo'
  end
end

A runnable example of this source code is available at this github repository.

Breaking down the above code, the first thing we do is inherit from AbstractController::Base:

class SearchRenderer < AbstractController::Base
  def initialize(search_results)
    @search_results = search_results
  end
end

We also save the search results in an instance variable so that our templates can access them later.

  include Rails.application.routes.url_helpers  # rails route helpers
  include Rails.application.helpers             # rails helpers under app/helpers

These methods return Rails route helpers like resource_path and resource_url, and also any helpers defined in app/helpers.

Next we add the mixins we need to be able to call the #render controller method. Calling #append_view_path sets up the view lookup path to be the same as our Rails controller views lookup path.

  include AbstractController::Rendering
  include AbstractController::Logger

  append_view_path "#{Rails.root}/app/views"

Then we define a controller action named execute that'll render out the response as a string. The #render method used here is very similar to the one used by ActionController.

  def execute
    render :action => 'foo'
  end

To use this renderer object, you need to initialize it with a search results object, and call #execute:

search_results = [{:foo => "bar"}, {:foo => "baz"}]
renderer = SearchRenderer.new(search_results)
renderer.execute

Rails ActionControllers are specific to HTTP, but its abstract parent class can be used to construct objects for generic controller objects for coordinating actions outside of an HTTP context. Custom controller objects can be composed with the available mixins to add common functionality such as rendering. These custom controllers can also share code with existing Rails applications DRY up templates and helpers.

Rack::Stream is rack middleware that lets you write streaming API endpoints that understand HTTP, WebSockets, and EventSource. It comes with a DSL and can be used alongside other rackable web frameworks such as Sinatra and Grape.

Normally, when an HTTP request is made, the server closes the connection when it's done processing the request. For streaming HTTP, also known as Comet, the main difference is that the server doesn't close the connection and can continue sending data to the client at a later time.

To prevent the connection from closing, rack-stream uses Thin's 'async.callback' to defer closing the connection until either the server decides to close the connection, or the client disconnects.

Rack::Stream is rack middleware that lets you write streaming HTTP endpoints that can understand multiple protocols. Multiple protocols means that you can write an API endpoint that works with curl, but that same endpoint would also works with WebSockets in the browser. The simplest streaming API you can make is:

# config.ru
# run with `thin start -p 9292`
require 'rack-stream'

class App
  def call(env)
    [200, {'Content-Type' => 'text/plain'}, ["Hello", " ", "World"]]
  end
end

use Rack::Stream
run App

If you ran this basic rack app, you could then use curl to stream it's response:

> curl -i -N http://localhost:9292/

HTTP/1.1 200 OK
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: close
Server: thin 1.3.1 codename Triple Espresso

Hello World

This isn't very exciting, but you'll notice that the Transfer-Encoding for the response is set to chunked. By default, rack-stream will take any downstream application's response bodies and stream them over in chunks. You can read more about chunked transfer encoding on Wikipedia.

Let's spice it up a bit and build an actual firehose. This next application will keep sending data to the client until the client disconnects:

require 'rack-stream'

class Firehose
  include Rack::Stream::DSL

  def call(env)
    EM.add_periodic_timer(0.1) {
      chunk "\nChunky Monkey"
    }
    [200, {'Content-Type' => 'text/plain'}, ['Hello']]
  end
end

use Rack::Stream
run Firehose

The first thing to notice is the Firehose rack endpoint includes Rack::Stream::DSL. This are convenience methods that allow you to access env['rack.stream'], which is injected into env whenever you use Rack::Stream. When a request comes in, the #call method schedules a timer that runs every 0.1 seconds and uses the #chunk method to stream data. If you run curl, you would see:

> curl -i -N http://localhost:9292/

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: close
Server: thin 1.3.1 codename Triple Espresso

Hello
Chunky Monkey
Chunky Monkey
Chunky Monkey
# ... more monkeys

rack-stream also allows you to register callbacks for manipulating response chunks, and controlling when something is sent with different callbacks. Here's a more advanced example with callbacks added:

require 'rack-stream'

class Firehose
  include Rack::Stream::DSL

  def call(env)
    after_open do
      chunk "\nChunky Monkey"
      close  # start closing the connection
    end

    before_chunk do |chunks|
      chunks.map(&:upcase)  # manipulate chunks
    end

    before_close do
      chunk "\nGoodbye!"  # send something before we close
    end

    [200, {'Content-Type' => 'text/plain'}, ['Hello']]
  end
end

use Rack::Stream
run Firehose

If you ran curl now, you would see:

> curl -i -N http://localhost:9292/

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: close
Server: thin 1.3.1 codename Triple Espresso

HELLO
CHUNKY MONKEY
GOODBYE!

For details about the callbacks, see the project page.

Up until this point, I've only used curl to demonstrate hitting the rack endpoint, but one of the big benefits of rack-stream is that it'll automatically recognize WebSocket and EventSource requests and stream through those as well. For example, you could write an html file that accesses that same endpoint:

<html>
<body>
  <script type='text/javascript'>
    var socket       = new WebSocket('ws://localhost:9292/');
    socket.onopen    = function()  {alert("socket opened")};
    socket.onmessage = function(m) {alert(m.data)};
    socket.onclose   = function()  {alert("socket closed")};
  </script>
</body>
</html>

Whether you access the endpoint with curl, ajax, or WebSockets, your backend API logic doesn't have to change.

For the last example, I'll show a basic chat application using Grape and Rails. The full runnable source is included in the examples/rails directory.

require 'grape'
require 'rack/stream'
require 'redis'
require 'redis/connection/synchrony'

class API < Grape::API
  default_format :txt

  helpers do
    include Rack::Stream::DSL

    def redis
      @redis ||= Redis.new
    end

    def build_message(text)
      redis.rpush 'messages', text
      redis.ltrim 'messages', 0, 50
      redis.publish 'messages', text
      text
    end
  end

  resources :messages do
    get do
      after_open do
        # subscribe after_open b/c this runs until the connection is closed
        redis.subscribe 'messages' do |on|
          on.message do |channel, msg|
            chunk msg
          end
        end
      end

      status 200
      header 'Content-Type', 'application/json'
      chunk *redis.lrange('messages', 0, 50)
      ""
    end

    post do
      status 201
      build_message(params[:text])
    end
  end
end

This example uses redis pubsub to push out messages that are created from #post. Thanks to em-synchrony, requests are not blocked when no messages are being sent. It's important do the redis subscribe after the connection has been opened. Otherwise, the initial response won't be sent.

socket.io is great because it provides many transport fallbacks to give maximum compatibility with many different browsers, but its pubsub interface is too low level for capturing common app semantics. The application developer doesn't have nice REST features like HTTP verbs, resource URIs, parameter and response encoding, and request headers.

The goal of rack-stream is to provide clean REST-like semantics when you're developing, but allow you to swap out different transport protocols. Currently, it supports normal HTTP, WebSockets, and EventSource. But the goal is to support more protocols over time and allow custom protocols. This architecture allows socket.io to become another protocol handler that can be plugged into rack-stream. If you wanted to use Pusher as a protocol, that could also be written as a handler for rack-stream.

rack-stream aims to be a thin abstraction that lets Ruby developers write streaming APIs with their preferred frameworks. I plan to broaden support and test against common use cases and popular frameworks like Sinatra and Rails. If you have any questions or comments, feel free to submit an issue or leave a comment below!

The Rails guide for ActiveRecord Validations and Callbacks is a good starting point for an introduction of the available callbacks and what they do. Most developers will be familiar with the validation and persistence callbacks, so let's start with these

:before_validation, :after_validation
:before_save, :after_save
:before_create, :after_create
:before_update, :after_update
:before_destroy, :after_destroy

The callbacks above are self explanatory and commonly used, but if you're unfamiliar with them, or need a refresher, check out the Rails guide on the topic.

For save, create, update, and destroy, Rails also gives extra helper methods for defining both a before and after save callback at the same time.

For example, suppose you wanted to trigger your own custom callback while a model was being destroyed. You can do so by defining and triggering your own callback as follows:

class SomeModel < ActiveRecord::Base
  define_callbacks :custom_callback

  around_destroy :around_callback

  def around_callback
    run_callbacks :custom_callback do
      yield  # runs the actual destroy here
    end
  end
end

Most of the time, your Rails models will be using ActiveModel, but sometimes it makes sense to use a plain old ruby object. Wouldn't it be nice if we could define callbacks in the same way? Fortunately, the callback system is neatly abstracted into ActiveSupport::Callbacks so it's easy to mix into any ruby class.

# Look Ma, I'm just a normal ruby class!
class Group
  include ActiveSupport::Callbacks
  define_callbacks :user_added

  def initialize(opts = {})
    @users = []
  end

  # Whenever we add a new user to our array, we wrap the code
  # with `run_callbacks`. This will run any defined callbacks
  # in order.
  def add_user(u)
    run_callbacks :user_added do
      @users << u
    end
  end
end

For a fully documented and runnable example, check out this github project. It'll also give some extra explanation about call order and inheritance.

• :after_initialize is called right after an object has been unmarshalled from the database. This allows you to do any other custom initialization you want. Instead of defining an initialize method on a model, use this instead.

• :after_find hasn't been useful in my experience. I haven't run into a case where I wanted to manipulate documents after a find action. It could potentially be useful for metrics and profiling.

• :after_touch. ActiveRecord allows you to touch a record or its association to refresh its updated_at attribute. I've found this callback useful to triggering notifications to users after a model has been marked as updated, but not actually changed.

• :after_commit is an interesting and tricky callback. Whenever ActiveRecord wants to make a change to a record (create, update, destroy), it wraps it around a transaction. after_commit is called after you're positive that something has been written out to the database. Because it is also called for destroys, it makes sense to scope the callback if you intend to use it only for saves. Be warned that after_commit can be tricky to use if you're using nested transactions. That'll probably be the topic of another post though.

# call for creates, updates, and deletes
after_commit :all_callback

# call for creates and updates
after_commit :my_callback, :if => :persisted?

• :after_rollback is the complement to after_commit. I haven't used it yet, but I can see it as being useful for doing manual cleanup after a failed transaction.

While many of our models will be backed with ActiveRecord, or some ActiveModel compatitible datastore, it's nice to see how easy it is to follow a similar pattern in normal ruby without having to depend on Rails.

If I told you that a page took 130 requests to load 170 KB of data? Would you call that a slow page?

This is a trick question, and the numbers I gave are a double red herring. A page is slow when it feels slow to a user. Without having opened up the page for yourself in a browser, you can't have a real answer.

But if your gut reaction was "yeah, that's damn slow", I wouldn't blame ya. It sounds like a ton of requests for the amount of data being transferred. To disprove that the page is slow, here's a screenshot of the requests in Chrome:

The page is question is the index page to my Facebook profile. Notice how almost all of the requests are being sent in parallel, and most of them finishing concurrently before the actual page skeleton has finished receiving the data.

As web developers, we've internalized two guidelines:

• minimize the number of requests
• reduce the size of the response

By themselves, these are good guidelines for web throughput performance. Where we go wrong is when these guidelines are applied without considering how the user will perceive the page load. There are times where it makes sense to have more requests rather than fewer in order to reduce page load times. What we should prioritize is page latency rather than page throughput. Facebook wrote a great blog post on this subject. They decomposed a large monolithic page into a bunch of independent 'pagelets' which can be generated, fetched, and rendered independently of one another.

With Opperator, we recognize speed as a feature. And by designing our architecture to be a set of loosely coupled services from day one, it was natural and easy to make our pages feel fast. On top of the advice listed by Facebook, here are some tips and notes about how we keep our pages speedy.

Don't serve a giant JSON object of all a resource with all of it's associations. Instead, serve only what you need, when you need it. For example, in our models, a Project has many Services. But when you make a request for a Project, the JSON response only includes a list of Service id's rather than the full JSON for the Project. Of course, sometimes it makes sense to pre-fetch associated objects, but this shouldn't be the default case.

As users, we don't feel page throughput, we feel page latency. It's ok for your page to take slightly longer time to load, as long as everything the user cares about can be seen as quickly and as smoothly as possible. The priority we choose to serve our content is:

CSS goes first to make sure the rendering of the page feels smooth and natural. We don't want any flashes of unstyled elements.

HTML page skeleton is loaded next to give overall structure and flat content to the site. Flat content anything that isn't session dependent or javascript dependent. Having this structure static will also help your SEO rankings because no dynamic content rendering needs to happen server side. This topic deserves it's own separate blog post.

Javascript is compressed loaded with require.js asynchronously with web modules. Javascript builds all the interactive elements on the page.

Images are sprited and loaded as late as possible, with the exception of anything that makes the page reflow and jerk.

Our business logic lives within a Grape API. The initial page load is a static HTML skeleton that is then bound to Javascript event handlers which will populate the content from the API backend. We use Ember.js (aka Sproutcore 2.0) to control and render all the frontend interaction.

Set your HTTP cache headers properly. If nothing has changed, then your backend doesn't have to regenerate a full response. Better yet, if something can safely be cached for longer, then your backend might not be hit at all.

Think of a CDN as a proxy layer in front of your app. By offloading your static assets into the CDN, your app no longer has to worry about serving those static assets. Not only is it less work and bandwidth on your backend, it's also faster for your users since the CDN's edge servers will be physically closer to your users. Two low-cost CDN providers worth checking out are:

Cloudflare is a relative newcomer to the arena. They range from free to $20/mo for your first site. That's hard to beat.

If you store your static assets in S3, then Amazon Cloudfront is worth a look. It allows you to configure serving S3 assets through their CDN. Pricing is based on usage.

Our website is actually deployed to a different server than our API. Technically, we could get a performance boost if they lived on the same box to cut down on network latency. But we decided to tradeoff network latency for clean separation of systems. There's always room down the line for further optimization, so "fast enough" for today is good enough for us.

What speed optimizations do you use on your site? Sound off in the comments

Out of the box, Faraday functions like a normal HTTP client with a easy to use interface.

Faraday.get 'http://example.com'

Alternatively, you can initialize a Faraday::Connection instance:

conn = Faraday.new
response = conn.get 'http://example.com'
response.status
response.body

conn.post 'http://example.com', :some_param => 'Some Value'
conn.put  'http://example.com', :other_param => 'Other Value'
conn.delete 'http://example.com/foo'
# head, patch, and options all work similarly

Parameters can be set inline as the 2nd hash argument. To specify headers, add optional hash after the parameters argument or set them through an accessor:

conn.get 'http://example.com', {}, {'Accept' => 'vnd.github-v3+json'}

conn.params  = {'tesla' => 'coil'}
conn.headers = {'Accept' => 'vnd.github-v3+json'}

If you have a restful resource you're accessing with a common base url, you can pass in a :url parameter that'll be prefixed to all other calls. Other request options can also be set here.

conn = Faraday.new(:url => 'http://example.com/comments')
conn.get '/index'  # GET http://example.com/comments/index

All HTTP verb methods can take an optional block that will yield a Faraday::Request object:

conn.get '/' do |request|
  request.params['limit'] = 100
  request.headers['Content-Type'] = 'application/json'
  request.body = "{some: body}"
end

payload = { :name => 'Maguro' }

# uploading a file:
payload = { :profile_pic => Faraday::UploadIO.new('avatar.jpg', 'image/jpeg') }

# "Multipart" middleware detects files and encodes with "multipart/form-data":
conn.put '/profile', payload

Basic and Token authentication are handled by Faraday::Request::BasicAuthentication and Faraday::Request::TokenAuthentication respectively. These can be added as middleware manually or through the helper methods.

conn.basic_auth('pita', 'ch1ps')
conn.token_auth('pitach1ps-token')

To specify an HTTP proxy:

Faraday.new(:proxy => 'http://proxy.example.com:80')
Faraday.new(:proxy => {
  :uri      => 'http://proxy.example.com',
  :user     => 'foo',
  :password => 'bar'
})

See the Setting up SSL certificates wiki page.

conn = Faraday.new('https://encrypted.google.com', :ssl => {
  :ca_path => "/usr/lib/ssl/certs"
})
conn.get '/search?q=asdf'

Like a Rack app, a Faraday::Connection object has a list of middlewares. Faraday middlewares are passed an env hash that has request and response information. Middlewares can manipulate this information before and after a request is executed.

To make this more concrete, let's take a look at a new Faraday::Connection:

conn = Faraday.new
conn.builder

> #<Faraday::Builder:0x00000131239308
    @handlers=[Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp]>

Faraday::Builder is analogus to Rack::Builder. The newly initialized Faraday::Connection object has a middleware Faraday::Request::UrlEncoded in front of an adapter Faraday::Adapter::NetHttp. When a connection object executes a request, it creates a shared env hash, wraps the outer middlewares around each inner middleware, and executes the call method. Also like a Rack application, the adapter at the end of the builder chain is what actually executes the request.

Middlewares can be grouped into 3 types: request middlewares, response middlewares, and adapters. The distinction between the three is cosmetic. The following two initializers are equivalent:

Faraday.new do |builder|
  builder.request  :retry
  builder.request  :basic_authentication, 'login', 'pass'
  builder.response :logger
  builder.adapter  :net_http
end

Faraday.new do |builder|
  builder.use Faraday::Request::Retry
  builder.use Faraday::Request::BasicAuthentication, 'login', 'pass'
  builder.use Faraday::Response::Logger
  builder.use Faraday::Adapter::NetHttp
end

If you wanted to use a different HTTP adapter, you can plug one in. For example, to use a EventMachine friendly client, you can switch to the EMHttp adapter:

conn = Faraday.new do |builder|
  builder.use Faraday::Adapter::EMHttp

  # alternative syntax that looks up registered adapters from lib/faraday/adapter.rb
  builder.adapter :em_http
end

Currently, the supported adapters are Net::HTTP, EM::HTTP, Excon, and Patron.

The order in which middleware is stacked is important. Like with Rack, the first middleware on the list wraps all others, while the last middleware is the innermost one, so that's usually the adapter.

conn = Faraday.new(:url => 'http://sushi.com') do |builder|
  # POST/PUT params encoders:
  builder.request  :multipart
  builder.request  :url_encoded

  builder.adapter  :net_http
end

This request middleware setup affects POST/PUT requests in the following way:

1. Request::Multipart checks for files in the payload, otherwise leaves everything untouched;
2. Request::UrlEncoded encodes as "application/x-www-form-urlencoded" if not already encoded or of another type

Swapping middleware means giving the other priority. Specifying the "Content-Type" for the request is explicitly stating which middleware should process it.

Examples:

payload = { :name => 'Maguro' }

# uploading a file:
payload = { :profile_pic => Faraday::UploadIO.new('avatar.jpg', 'image/jpeg') }

# "Multipart" middleware detects files and encodes with "multipart/form-data":
conn.put '/profile', payload

Each Faraday::Connection instance has a Faraday::Builder instance that can be used to manipulate the middlewares stack.

conn = Faraday.new
conn.builder.swap(1, Faraday::Adapter::EMHttp)  # replace adapter
conn.builder.insert(0, MyCustomMiddleware)      # add middleware to beginning
conn.builder.delete(MyCustomMiddleware)

For a full list of actions, take a look at the Faraday::Builder documentation.

Middleware are classes that respond to call. They wrap the request/response cycle. When it's time to execute a middleware, it's called with an env hash that has information about the request and response. The general interface for a middleware is:

class MyCustomMiddleware
  def call(env)
    # do something with the request

    @app.call(env).on_complete do |env|
      # do something with the response
      # env[:response] is now filled in
    end
  end
end

It's important to do all processing of the response only in the on_complete block. This enables middleware to work in parallel mode where requests are asynchronous.

env is a hash with symbol keys that contains info about the request and response.

:method - a symbolized request method (:get, :post, :put, :delete, :option, :patch)
:body   - the request body that will eventually be converted to a string.
:url    - URI instance for the current request.
:status           - HTTP response status code
:request_headers  - hash of HTTP Headers to be sent to the server
:response_headers - Hash of HTTP headers from the server
:parallel_manager - sent if the connection is in parallel mode
:request - Hash of options for configuring the request.
  :timeout      - open/read timeout Integer in seconds
  :open_timeout - read timeout Integer in seconds
  :proxy        - Hash of proxy options
    :uri        - Proxy Server URI
    :user       - Proxy server username
    :password   - Proxy server password
:response - Faraday::Response instance. Available only after `on_complete`
:ssl - Hash of options for configuring SSL requests.
  :ca_path - path to directory with certificates
  :ca_file - path to certificate file

Faraday::Adapter::Test is an HTTP adapter middleware that lets you to fake responses.

# It's possible to define stubbed request outside a test adapter block.
stubs = Faraday::Adapter::Test::Stubs.new do |stub|
  stub.get('/tamago') { [200, {}, 'egg'] }
end

# You can pass stubbed request to the test adapter or define them in a block
# or a combination of the two.
test = Faraday.new do |builder|
  builder.adapter :test, stubs do |stub|
    stub.get('/ebi') {[ 200, {}, 'shrimp' ]}
  end
end

# It's also possible to stub additional requests after the connection has
# been initialized. This is useful for testing.
stubs.get('/uni') {[ 200, {}, 'urchin' ]}

resp = test.get '/tamago'
resp.body # => 'egg'
resp = test.get '/ebi'
resp.body # => 'shrimp'
resp = test.get '/uni'
resp.body # => 'urchin'
resp = test.get '/else' #=> raises "no such stub" error

# If you like, you can treat your stubs as mocks by verifying that all of
# the stubbed calls were made. NOTE that this feature is still fairly
# experimental: It will not verify the order or count of any stub, only that
# it was called once during the course of the test.
stubs.verify_stubbed_calls

• faraday-middleware - collection of Faraday middlewares.
• faraday_yaml - yaml request/response processing

If you want to follow along in the code, I recommend cloning the Rails repository. The cache related code I'm covering all live within activesupport/lib/cache.rb and activesupport/lib/cache folder. The corresponding tests live in activesupport/test/caching_test.rb.

All cache store implementations inherit from an abstract store named ActiveSupport::Cache::Store. This class defines the public interface that's used by Rails to do caching. The three basic operations are read, write, and delete. Here's a simple example you can run in irb:

require 'activesupport'
cache = ActiveSupport::Cache.lookup_store(:memory_store)
cache.read('foo')
=> nil
cache.write('foo', 'bar')
cache.read('foo')
=> 'bar'
cache.delete('foo')
cache.read('foo')
=> nil

After requiring activesupport, we ask for an instance of a MemoryStore (we'll cover the different store types later in this post). The interface for read, write, and delete are self explanatory. You can also customize the behavior of these actions.

The concrete store implementations are well documented, so I'll introduce them briefly here and leave the details to the documentation.

• MemoryStore - a cache store that stores data in a plain-old Ruby hash. As an added feature, it keeps track of cache access and cache size, and will prune the cache when it hits a customizable max size.

• FileStore - a cache store that stores data on the filesystem. It also caches multiple read calls within the same block in memory to decrease I/O.

• MemCacheStore - the big daddy of cache stores. Backed by memcached, this store allows you to specify multiple memcached servers and load balances between them.

• NullStore - Interesting cache store that does nothing. That's right, if you look at its implementation, it's just a bunch of empty methods. It's perfect for use as a mock cache store for testing, or as a template for writing your own cache store.

By default, Rails 3 will initialize a FileStore that you can reference through Rails.cache. This cache is used internally by Rails to cache classes, pages, actions, and fragments. If you want to change which cache store is used, you can configure it in your application.rb

# use a MemoryStore cache with a max size of 512 megabytes
config.cache_store = [:memory_store, {:size => 536870912}]

In production mode, Rails will also insert Rack::Cache to the top of the middleware stack and use Rails.cache as its storage. Note that even though Rack::Cache's heap storage does not bound the size of its cache, if you use ActiveSupport's MemoryStore, the least recently used entries will be pruned from the cache when it hits your specified limit. So if you set correct cache headers, Rack::Cache will pick them and cache your responses.

The default cache stores are a perfect fit for most situations, but if you do need to write a custom cache store, rest assured that it's easy to do.

The three main methods to override are:

# Read an entry from the cache implementation. Subclasses must implement this method.
def read_entry(key, options) # :nodoc:
  raise NotImplementedError.new
end

# Write an entry to the cache implementation. Subclasses must implement this method.
def write_entry(key, entry, options) # :nodoc:
  raise NotImplementedError.new
end

# Delete an entry from the cache implementation. Subclasses must implement this method.
def delete_entry(key, options) # :nodoc:
  raise NotImplementedError.new
end

These methods are then used by the public interface methods. There are a few methods you can optionally implement, but your cache will work with just the three listed above.

For a client project, I wrote a write-through cache store called CascadeCache that chains multiple cache stores together. For example, here's one possible configuration:

config.cache_store = [:cascade_store, {
  :stores => [
    [:memory_store, :size => 5.megabytes],
    [:memcache_store, 'somehost:11211']
  ]
}]

The behavior of this cache store is to return the first hit from the list of caches. This allows the app to have a small low-latency MemoryStore in front of a MemCacheStore. If something can't be found in the MemoryCache, then we fall back to MemCache. When writing to the cache, entries are written through to both underlying cache stores. The primary reason for doing this wasn't because MemCache store was slow, but as an extra backup cache in case MemCache became temporarily unavailable (actually happened in production).

I'm hoping CascadeCache makes it upstream into ActiveSupport, but in the meantime, I've packaged it up as a separate gem. For another example of a custom cache implementation, check out redis-store. It includes an ActiveSupport compatible cache.

Caching is a tricky beast. On top of deciding what to cache and when to expire, the underlying cache store can affect your app's performance. Choose the cache store that best fits your needs, use a hybrid CascadeCache, or write your own. Good luck and happy tuning!

You've heard of Pry right? It's a full-featured alternative to the classic IRB shell that we use in Ruby, and it's awesome sauce. If you've ever felt like you wanted a crowbar to pry open your code during runtime... well, Pry is your answer.

Pry is essentially a REPL (read–eval–print loop) tool that you can use to examine and debug your code. One of the best features is that local variables are available to Pry, saving you from recreating them as you normally would in an IRB session.

I like to install pry into the global gemset since it's a tool even when I'm outside of a Rails project

rvm use @global
gem install pry

In your application initialization, add the following to replace IRB with pry by default. For example, Rails would add this code to config/initializers/pry.rb

begin
  require "pry"
  IRB = pry
rescue
  # do nothing if pry fails to load
end

Between different versions of Ruby, installing and requiring ruby-debug can lead to annoying problems. 1.8.7 uses ruby-debug, 1.9.2 requires ruby-debug19, and 1.9.3 blows up when you try to use ruby-debug19. ruby-debug also depends on the linecache gem, which sometimes requires extra work to use with rvm and sometimes fails in environments when the native extensions fail to build.

Instead, skip all that headache with Pry! Anywhere you would use a 'debugger' statement, just call:

binding.pry

'binding' is a reference to the current local context. Enter 'exit' when you're finished with debugging, and the code will resume executing

Pry has a ton of other productivity boosters built in. You can drop into a shell temporarily, browse docs without leaving your shell, edit and reload code, and send code snippets up to gist. For a full listing, check out their README

There's a ton of documentation for Pry and a growing community around it; if you're interested in jumping in be sure to start at their Github page for links to tutorials, screencasts, FAQs and a Wiki!

When building a product for your audience, you need to empathize with their pains and problems. It's one thing to imagine yourself in their proverbial shoes, but it's much more effective to just wear the same damn shoes. It means using your own product while you're building your product. Startup slang commonly refers to this as "dog-fooding", but I dislike this term because it evokes images of being forced fed something you don't want.

While it's important to focus on relieving your customers' pain, it's equally important to optimize your own happiness along the way. Not only will you enjoy your work more, your code will be "happier" as well. Allow me to explain what happy code looks like.

When Michael and I started Opperator, we aligned ourselves with our customers. When life sucks for our customers, life sucks for us. When life is awesome for our customers, life is also awesome for us. It's a very simple formula to balance: remove sucky things, and increase awesome things. Simple as this sounds, many entrepreneurs only tackle the former half of the formula. For any startup, there are many things that happen behind the scenes that your customers don't see. Things like code smells, technical debt, and shoddy documentation. But just because your customers don't see these things, doesn't mean that you don't.

We execute quickly on Opperator, but we also take the time to step back and holistically evaluate our product.

• Are we happy with the direction we're going?
• Are we happy with the code we've written?
• Do we feel mentally or physically burned out?

These aren't things that your customer will see. But over time, these things will add up. If you're not happy with working on your product, then your efforts will be forced, and the results will reflect this. Taking a small slice of time to take care of any of these points will yield long term results for your business and for yourself.

This tutorial builds up an HTML prototype from the bottom up to show how prototyping problems can be solved with compass and serve. To build an HTML prototype, you can skip all of the details and just run:

serve create my-project

Check out the serve documentation for more detail. To arrive at the same conclusion step-by-step, read the long version below.

We'll walk through the individual steps of building out a web prototype. We'll start with the bare minimum and add pieces as needed. The example design I'm using is the design for my car blog, and the final source can be found here on github.

The beauty of static pages is how quick it is to set one up. We'll worry about the other pages after we've happy with how the index page looks. For starters, let's create a basic page skeleton.

<html>
  <head></head>
  <body>
    <div id='header'>
      <a href='#'>Rocky Road Blog</a>
    </div>
    <div id='main'>
      <div id='post-list'>
        <div class='post'>
          <!-- blog post goes here -->
        </div>
      </div>
    </div>
    <div id='footer'>
      <p>Copyright 2011 RockyRoadBlog. All rights reserved</p>
    </div>
  </body>
</html>

To stub out image assets, I used LoremPixel. There's no styling at all, but the structure gives us a good idea of where everything will live.

Instead of writing raw CSS, it's much easier to write stylesheets with sass. Compass is another library that provides a bunch of useful sass mixins and functions. When paired with guard-compass, the stylesheets are compiled to css files whenever you save your sass files.

Add the following to a Gemfile

source "http://rubygems.org"

gem "compass"
gem "guard"
gem "guard-compass"

Then run:

bundle
bundle exec compass init --syntax=sass
bundle exec guard init

By default, compass uses the scss syntax, but I prefer the indentation based sass syntax instead. Skip the --syntax=sass if you prefer the default. Edit your Guardfile to look like the following:

guard "compass" do
  watch(%r{sass/*\.sass})
end

Let's add our first sass file and check that our setup is working. Add a main.sass to your sass/ subdirectory with the following:

body
  background-color: red

Add a line to index.html in the head section to reference the compiled stylesheet. Notice that we're referencing the compiled css file, not the original sass source file.

<link rel='stylesheet' type='text/css' href='stylesheets/main.css'>

Now start guard with:

bundle exec guard

You should see your sass source files compile. Now whenever you make changes to your sass files, guard will pick them up and recompile your sources.

When designing, it's common to have a chunk of markup that needs to be reused over and over. In our example, I'd like to see the design with multiple post elements at once. I could duplicate the markup several times, but that's a pain, and becomes even more painful when you have to change all of the duplicated markup if you want to make a change. What we ideally want is to have a separate file for the reusable snippets that we can include as many times as we'd like.

Serve does exactly that (and more). First let's get it installed by adding it to our Gemfile.

gem "serve"  # run "bundle" after editing

In serve, reusable snippets are called 'partials'. Partials live in a folder called views by default. To make a new partial for each individual blog post, we create a file named _post.erb with the html of a post:

<!-- in views/_post.erb -->
<div class='post'>
  <!-- blog post goes here -->
</div>

Whenever we want to reference that partial, we can include it in our other templates by calling render. For example, if we want to list 5 posts per index page, we can use a simple loop:

<!-- in index.html -->
<html>
  <head></head>
  <body>
    <div id='header'>
      <a href='#'>Rocky Road Blog</a>
    </div>
    <div id='main'>
      <div id='post-list'>
        <!-- renders 5 post divs -->
        <%= 5.times.each do %>
          <%= render 'post' %>
        <% end %>
      </div>
    </div>
    <div id='footer'>
      <p>Copyright 2011 RockyRoadBlog. All rights reserved</p>
    </div>
  </body>
</html>

To see this in action, run serve in your terminal, and visit http://localhost:4000. You should see the blog index page with 5 posts in it.

Our blog index page is starting to come together. But our blog will have other pages as well. There'll be an 'About' page and also a page to show a blog post and it's comments. These pages will share a lot of the same markup (the header, the footer, the page structure). Rather than pulling out partials for each of these, we can create a layout. Think of a layout as an inside-out partial. Instead of specifying which parts are the same, you specify which part will change. To create our layout, add the following to _layout.erb in the views directory.

<!-- views/_layout.erb -->
<html>
  <head></head>
  <body>
    <div id='header'>
      <a href='#'>Rocky Road Blog</a>
    </div>
    <div id='main'>
      <%= yield %>
    </div>
    <div id='footer'>
      <p>Copyright 2011 RockyRoadBlog. All rights reserved</p>
    </div>
  </body>
</html>