# Octa

> Systems notes & runtime investigations. Engineering lab documenting architecture decisions, runtime research, and performance investigations. By Christian Elías.

Each article is available as raw Markdown at `/doc/{slug}.md` (linked below) and as HTML at `/doc/{slug}/`.

## Architecture

- [Bifrost: what changed when a private tunnel became a public package](https://octa.page/doc/bifrost-multi-peer-tunnel-relay.md): Design changes required to turn a single-user WebSocket tunnel into a self-hostable package: named peers with subdomain routing, scoped tokens stored as SHA-256 hashes, backpressure limits, dead connection detection, and queue drain on disconnect.
- [Feature flag services don't store user IDs — and the consequence of that](https://octa.page/doc/feature-flags-stateless-users.md): Tessera stores no user records — rollout consistency comes from deterministic hashing, not a user registry. The consequence: exposure analytics require a separate events table. How LaunchDarkly, Statsig, and PostHog Flags handle the same tradeoff.
- [Separating the flag evaluation API from the dashboard in the same monorepo](https://octa.page/doc/feature-flags-hono-next-split.md): Why Tessera's feature flag evaluation API runs on Hono rather than Next.js API routes — cold start latency, deployment coupling, and framework overhead — and how a shared monorepo makes the split cheap while keeping evaluation logic in one place.
- [JSON-LD Entity Graph for Brand Disambiguation on Minimal Sites](https://octa.page/doc/jsonld-entity-graph-brand-disambiguation.md): How to use JSON-LD with @id, sameAs, and rel=me to establish a coherent entity graph that disambiguates a brand sharing its name with unrelated entities — the three-node minimum, Wikidata's role, and what structured data cannot do.
- [RSS as a cross-site content bridge in Astro SSG](https://octa.page/doc/rss-as-cross-site-content-bridge.md): Using RSS as a stateless content contract between two independent Astro static sites, with GitHub Actions repository_dispatch to trigger rebuilds only when Markdown content changes — not on every commit.
- [Using the URL fragment as an encryption key carrier](https://octa.page/doc/url-fragment-as-encryption-key.md): Client-side AES-256-GCM encryption where the key lives exclusively in the URL fragment — never transmitted to the server. The design, the constraints around browser history and intermediaries, and why out-of-band key delivery defeats the UX goal.
- [A WebSocket relay as a self-hosted tunnel](https://octa.page/doc/websocket-tunnel-relay.md): A single Node.js process that exposes localhost over public HTTPS using a persistent outbound WebSocket from the CLI — token auth in the handshake, request queuing with UUID correlation, 30s timeout, and no inbound ports on the developer's machine.
- [Building gob.co.nz: A Static Corrections Register](https://octa.page/doc/building-gob-co-nz.md): Architecture notes for gob.co.nz, a static public corrections register for the tech industry — stack decisions, Astro 6 Content Layer footguns, build-time OG image generation with sharp, and Pagefind client-side search integration.
- [Building Octa: Architecture Decisions for a Static Engineering Notebook](https://octa.page/doc/building-octa.md): Design decisions behind Octa: why Astro over Next.js, how the type/project dual-classification model works, the sidebar architecture, Mermaid diagram rendering without a build-time headless browser, and what was deliberately left out.

## Runtime

- [Injecting git config per-process with GIT_CONFIG_KEY_n](https://octa.page/doc/git-config-env-injection.md): Injecting git safe.directory per-process via GIT_CONFIG_COUNT and GIT_CONFIG_KEY_n environment variables — no file writes, no sudo — the correct fix for deploy agents running as root against repositories owned by www-data.
- [CSS print layout: floats, BFC, and image containment](https://octa.page/doc/css-print-float-bfc.md): Four print layout behaviors that break screen assumptions: why floats beat CSS Grid for variable-height sidebars, why DOM order matters for floats, why overflow:hidden on a float sibling breaks multi-page layouts, and how to draw rules that actually print.
- [tailscale serve sets REMOTE_ADDR to 127.0.0.1 for every request](https://octa.page/doc/tailscale-serve-remote-addr.md): tailscale serve is a reverse proxy, not a network filter — it collapses all caller identities to 127.0.0.1, silently bypassing any REMOTE_ADDR-based auth guard. The only reliable identity signal is the Tailscale-User-Login header it injects.

## Systems

- [Completing the IPoAC Stack: Why DoAC Had to Exist](https://octa.page/doc/completing-the-ipoac-stack.md): The IPoAC protocol family had no naming layer for 35 years. DoAC fills the gap with the AA resource record, the Pigeon of Last Resort bootstrap procedure, retransmission semantics calibrated for multi-day transit, and DNSSEC key distribution via Trusted Courier Pigeon.
- [Building @avelor/vhost: From Repeated Pain to Open Source Tool](https://octa.page/doc/building-avelor-vhost.md): @avelor/vhost generates Apache VirtualHost configs from a YAML file — with a managed-config marker for gradual migration, a default-vhost that blocks unrecognized requests, and content-negotiated error pages that serve HTML or JSON based on the Accept header.

## Notes

- [Serving every article as an RFC-style plain text document](https://octa.page/doc/serving-articles-as-rfcs.md): Every article now has a /doc/:slug.txt version rendered as a classic IETF RFC: 72-column body, chronological OCTA-n numbering, numbered sections, links collected into a References section — generated at build time from the Markdown source with marked's lexer.
- [My First Internet Draft: DNS over Avian Carriers](https://octa.page/doc/my-first-internet-draft.md): Notes on submitting draft-cruzgonzalez-ipoac-dns-00 to the IETF: what DoAC specifies, the AA resource record wire format, the Pigeon of Last Resort bootstrap problem, DNSSEC over Trusted Courier Pigeon, and the path to publication as an April Fools RFC.
- [floo: a minimal deploy agent for self-hosted VPS](https://octa.page/doc/floo-deploy-agent.md): floo runs an HTTP deploy agent on the server with YAML-defined project steps, scoped tokens stored as SHA-256 hashes, and real-time log streaming via SSE. systemd as the process supervisor, no Docker, no managed platforms.
- [Why I Built mesh: Local Dev Proxy with Named Services and Failure Injection](https://octa.page/doc/why-i-built-mesh.md): mesh is a local dev proxy where services get names instead of port numbers, and a YAML rules block injects failures at the network layer — 503s, delays, per-request rates — without touching backend code or adding mocks.
- [CV as Code: Generating a PDF from an Astro page with Playwright](https://octa.page/doc/cv-as-code-playwright-pdf.md): Generating a print-ready PDF CV from a static Astro page using Playwright headlessly — why @page margins are ignored by Playwright, why astro-pdf was skipped, and ATS compatibility pitfalls with em dashes and special characters.
- [av.js — self-hosted analytics embed](https://octa.page/doc/av-js-analytics-embed.md): API reference for av.js: the minimal analytics snippet for Avelor-hosted projects. Covers the embed pattern, the pageview payload structure, custom event API, session ID strategy, and implementation constraints like keepalive fetches and localhost filtering.

## Timezone

- [Leap Seconds After 2035: What Was Actually Decided, and the Proposals on the Table](https://octa.page/doc/retiring-leap-seconds.md): The 2022 CGPM resolution doesn't abolish leap seconds — it raises the tolerated UT1−UTC difference, with the practical effect that insertions cease. A survey of replacement proposals (leap minute, Levine's rate adjustments, BIPM's Continuous UTC group) plus a 4-year scheduled-block variant.
- [Timezone Propagation: How IANA Changes Reach Your Application](https://octa.page/doc/timezone-propagation-flow.md): How IANA timezone changes travel from the tzdb release through CLDR, OS updates, and language runtimes — including Node.js's Date/Intl split where the same environment can produce two different answers, and the British Columbia permanent DST workaround.

## Optional

- [RSS feed](https://octa.page/rss.xml)
- [Search index (JSON)](https://octa.page/search.json)