DEV Community: Ravi Kishan

GUML: Let the Model Write 24 Lines and the Compiler Write the Other 229

Ravi Kishan — Fri, 16 Oct 2026 05:14:04 +0000

TL;DR: GUML is a tiny, indentation-based UI language designed to be written by a language model, and a Rust compiler that turns it into React, Svelte 5, static HTML, Web Components, a JSON UI tree, A2UI or MCP-UI. The model writes 24 lines. The compiler writes the fetch, the abort, the retry with backoff, the stale-while-revalidate cache, the optimistic update, the rollback and the accessible names: 253 lines of React for the task app below. Every error comes back in one pass, with a code and a suggestion, and the obvious ones are fixed without asking the model again.
cargo install guml-cli     # the `guml` command
pnpm add @guml/core        # the same compiler as WebAssembly
pip install guml           # and from Python
🔗 GitHub · 📦 @guml/core on npm · 📄 Research report

Why I built this
The 24-line argument
A tour of the language
Inside the compiler
A lexer that cannot decide alone
Every error in one pass
Did you mean card?
Repair without a model
What 24 lines become
Seven backends, one vocabulary
Themes and capabilities
What is measured, and what is not
A real model tried it
The playground and the chat
Proof: what I ran for this post
What I found while writing this
The question still open
What I learned
What's next
Try it

Why I built this

Ask any AI app builder for a task list and watch what comes back: two hundred lines of React. useState, useEffect, an AbortController, a loading flag, an error flag, an optimistic update, a rollback, a className string per element, and aria-labels if you're lucky.

Almost none of that is a decision. It's convention: the same fetch-with-cancellation shape, the same rollback, the same focus ring. The model is being paid, in tokens, in latency and in error probability, to re-derive a compiler's output by hand, every single time.

Tailwind makes the point sharply. className="mt-6 flex items-center justify-center gap-3" is about fourteen tokens that express three tokens of intent: row, centered, normal gap.

So the question behind GUML is simple: what if the model only wrote the decisions, and a compiler wrote the conventions? There's no widely used representation that sits between "natural-language prompt" and "framework source code". Every AI builder jumps the whole distance in one hop. GUML is the stop in the middle.

Diagram from the original.

The dashed box is the whole idea. Nothing in it appears in the source the model writes, so the model can't spend tokens on it, and it can't get it wrong.

The 24-line argument

This is the task-list fixture, fixtures/b.guml, complete:

page Tasks

type Task {id, title, done:bool, createdAt:date}
data tasks:Task[] GET /api/tasks
  add  POST   /api/tasks      {title} optimistic:prepend
  save PATCH  /api/tasks/{id} {done}  optimistic
  drop DELETE /api/tasks/{id}         optimistic

state draft=""
state filter=all|open|done

head Tasks — {tasks.open.count} open

form >tasks.add{title:draft}; draft=""
  input draft aria="New task" placeholder="Add a task…"
  btn Add primary disabled={!draft.trim()} busy="Adding…"

tabs filter

list tasks where={filter}
  check {done} >tasks.save
  text {title} strike={done}
  btn Delete quiet aria="Delete {title}" >tasks.drop
  empty Nothing here yet.

Read it once and you know the whole app: a typed resource with three mutations (two of them optimistic), a text draft, a three-way filter, a live count in the heading, a form, tabs, and a list with an empty state.

Here it is compiled in the browser. This is the docs playground running the Rust compiler as WebAssembly:

Notice the small line under the input: tabs — not lowered by this compiler version. The in-browser preview renderer doesn't draw tabs yet, and it says so instead of drawing something approximate. That's one of the project's four invariants, and it'll come up again.

A tour of the language

The whole syntax fits in a paragraph, which is the point: the full spec plus the vocabulary costs a model about 2,935 estimated tokens of prompt, and the spec file states a budget of 3,000.

Lines are structure. Indentation is nesting, 2 spaces per level. No closing tags, no braces for blocks, no imports. A tab is an error (GUML0001).

Directives declare the data model:

page Counter title="Clicks"                 // name -> component
type Task {id, title, done:bool}           // fields default to string
state count=0                              // type inferred from the initial value
state filter=all|open|done                 // an enumerated domain; first value is initial
data tasks:Task[] GET /api/tasks           // a resource
  add  POST   /api/tasks      {title}  optimistic:prepend
on {filter} >tasks.list                    // an effect: re-runs when filter changes

Elements are tag [positionals] [name=value] [>action]. Positionals can be a label, a modifier, a {binding}, a /route or an #anchor. The action comes last because > swallows the rest of the line.

Bindings are read-only expressions: paths, comparison, boolean logic, arithmetic, and a fixed set of aggregates (.count .sum .open .done .trim .lower .upper). {tasks.open.count} is "how many rows have the bool field unset". It works on invoices too, where the bool is paid, because the compiler reads the flag from the row type rather than from a name it hoped for.

Actions are statements separated by ;: >count++, >count=0, >tasks.add{title:draft}; draft="".

The vocabulary is closed. There are 49 primitives in a registry (card row col section nav hero form tabs list table btn input select metric modal toast…), 24 modifiers (primary ghost quiet danger sm lg center between…), and 12 global attributes. There is no class attribute: presentation belongs to the theme.

def declares a user component. It's a compile-time macro with parameters and one slot, and by the time codegen runs there's no trace of it.

Two conformance levels. core is markup only: no I/O, no state, meant to be safe to render from an untrusted agent. app adds state, data, actions and the repeaters. An app construct at the core level is GUML0091.

Escape hatches. js and raw blocks pass through verbatim and unchecked. Each one emits a GUML0090 note, so the escape-hatch rate stays countable. That rate is one of the things the research measures.

Inside the compiler

The compiler is a Rust workspace of 14 crates, about 33,000 lines. The heaviest are guml-compiler (about 10.7k lines, the analysis passes) and guml-codegen (about 9.1k lines, the backends).

The driver is short enough to quote. From crates/guml-compiler/src/lib.rs:

let parsed = guml_parser::parse(src, reg);
// ...
expand::expand(&mut program, &mut diagnostics);      // def macros
sema::analyse(&program, reg, &mut diagnostics);      // scope + accessibility
validate::validate(&program, reg, &mut diagnostics); // structure, methods, unused
types::check(&program, &mut diagnostics);            // expression types, aggregates

Diagram from the original.

All the analysis passes always run, even after an error, so diagnostics accumulate. Codegen runs only on an error-free program. There's no separate IR: the AST, guml_ast::Program, is what every backend consumes, and each backend lowers expressions through one shared function.

The type checker is the newest stage and, according to the docs, the one that paid for itself most directly. It found a live bug in a published example where {invoices.open.count} had been compiling to a filter on a field the type didn't declare: always zero, and no test noticed.

A lexer that cannot decide alone

GUML has an ambiguity no lexer can resolve on its own. The comment at the top of crates/guml-syntax/src/lib.rs puts it in two lines:

btn Decrement ghost >count--      // Decrement is a label, ghost is a modifier
p Press the buttons to change.    // the whole remainder is prose content

Same shape, opposite meanings. Whether the rest of a line is structure or prose depends on the tag, and the tag's kind lives in the registry. So the lexer produces both readings of every line: a token list and the raw text. Then the parser, which knows the registry, picks one.

The rule is subtle: a text tag stays prose unless the line contains an = whose name the registry accepts for that tag. So p Set x=1 to enable is prose, and text {title} strike={done} is structure. Step through it:

A frame from the interactive sketch in the original — watch it run.

Two more lexer decisions I like:

Actions terminate the line by construction. Everything after > is one token, so actions are lexable in a single pass with no lookahead.
URLs are an allow-list. A route is /path at token start, so $24/mo stays one word, and absolute URLs are limited to http:// and https://. As the comment says, a general "scheme followed by ://" rule would make javascript: and data: lexable as request targets. The allow-list is the security boundary.

Every error in one pass

This is the invariant I'd defend hardest, and the project's own CLAUDE.md says it plainly: "Each repair-loop round is a full LLM generation; single-error reporting is a product defect, not a style preference."

A compiler that stops at the first error is fine for a human, who fixes one thing and presses save. For a model it's a disaster: each round trip is a full generation, billed at output rates. So the parser recovers from everything:

An unknown tag is reported, with a suggestion, and then parsed as a container anyway, so errors in its children still surface.
A missing attribute value is reported and parsing continues.
Bad indentation is reported once per run, not once per line. Before that fix, one mis-indented section produced 15 stray GUML0011s, and a repair loop handed sixteen errors will edit sixteen lines, fifteen of which were correct.

Here's the playground's deliberately broken sample, three mistakes from three different passes:

And the same file from the CLI, exactly as guml check printed it on my machine:

error[GUML0030]: unknown tag `crad`
  --> broken.guml:4:1
   |
  4 | crad sm center
   | ^^^^
   = help: did you mean `card`?
   = suggestion: card

error[GUML0033]: binding refers to `kount`, which is not declared
  --> broken.guml:6:3
   |
  6 |   metric {kount}
   |   ^^^^^^^^^^^^^^
   = help: did you mean `count`?
   = suggestion: count

error[GUML0050]: `btn` has no accessible name
  --> broken.guml:7:3
   |
  7 |   btn quiet >count++
   |   ^^^^^^^^^^^^^^^^^^
   = help: give the control a text label, or add `aria="…"` describing what it does
   = suggestion: btn aria="…"

(Look closely at the carets under metric {kount}. They'll matter later.)

Notice the third error. A button with no accessible name is a compile error, not a lint warning. The explain text says why: "an inaccessible interface is a broken interface, and the compiler is the last place able to notice."

Diagnostic codes are an API

There are 49 codes, GUML0001 to GUML0104, grouped in decades: lexical, layout, syntax, resolution, semantics, accessibility, types, structure, domains, escape hatches. They're append-only: a test enforces it, and the Rust enum is #[non_exhaustive]. The reason is that a repair loop keys on them, so GUML0033 has to mean the same thing forever. 0060 is deliberately unallocated, because "shipping a code with no emit site is how a diagnostic surface starts lying about what it can detect."

Every diagnostic is machine-actionable JSON:

{"code":"unknown_tag","id":"GUML0030","severity":"error","message":"unknown tag `crad`",
 "span":{"start":27,"end":31,"line":4,"col":1},"help":"did you mean `card`?","suggestion":"card"}

suggestion is present only when the fix is unambiguous, which is what lets a machine apply it without asking anyone.

Did you mean card?

How does the compiler know crad means card? The obvious answer is edit distance, and the obvious answer is wrong. Plain Levenshtein scores crad → card as 2 (two substitutions), which is too far for a four-letter word. Typos are very often swapped neighbours, so GUML uses Optimal String Alignment, which adds one more case to the recurrence:

$$
d(i,j)=\min\begin{cases}
d(i-1,j)+1 & \text{delete}\
d(i,j-1)+1 & \text{insert}\
d(i-1,j-1)+[a_i \neq b_j] & \text{substitute}\
d(i-2,j-2)+1 & \text{if } a_i=b_{j-1} \text{ and } a_{i-1}=b_j
\end{cases}
$$

Watch the two tables fill, and see where the transposition (highlighted) saves an edit:

A frame from the interactive sketch in the original — it does not render here.

The threshold is at most 1 edit for names of four characters or fewer, and at most 2 above that. But edit distance can't help with the most common mistake a model makes, which is writing HTML out of habit: button → btn is three edits. So before any distance is computed, the registry checks a table of 39 HTML habits (div→col, span→text, button→btn, hr→divider, ul→menu, dialog→modal…), and each entry carries a note explaining why GUML doesn't have that element.

Modifiers are stricter still: exactly one edit, on a word of at least four characters. That rule exists because of a real data-loss bug, where btn Click me was "fixed" to btn Click md.

Repair without a model

Models don't return clean files. They return Here you go:, a code fence, the code, another fence, and Let me know if you want changes!. guml repair strips that packaging and applies every unambiguous fix, with no model call, ever:

Layer	Fixes	Cost
`sanitize`	code fences, markdown rules, trailing commentary	free
`format`	indentation, tabs, spacing	free
`fix`	every unambiguous diagnostic suggestion, up to 3 rounds	free

Diagram from the original.

Two safety rules make this trustworthy. First, a layer that would increase the error count is discarded rather than kept: "deterministic" is not the same as "always an improvement". Second, a suggestion containing … is a template for a human (btn aria="…"), not a replacement, so it's shown and never applied. Splicing it in would put a literal ellipsis in the accessible name, which is worse than the original error.

I fed it the broken sample wrapped in a fence and some chat filler. The JSON report:

{"applied":["GUML0030"],"changed":true,"errorsBefore":7,"errorsAfter":2,"rounds":2,
 "sanitize":{"fence":true,"rules":0,"trailing":0}}

Seven errors down to two with zero tokens spent. The fence and the commentary are gone and crad became card. What's left are the two that genuinely need a decision: is kount a typo or a missing state, and what should this button say?

What 24 lines become

Here's the part the model never writes. These excerpts are real output from guml build fixtures/b.guml, 253 lines of React and TypeScript in total.

A retry helper that knows what's safe to retry. It uses exponential backoff (300 ms, then 600 ms), only for idempotent methods, only on a network failure or a 5xx, and never after an abort:

async function retrying(url: string, init: RequestInit = {}, tries = 3): Promise<Response> {
  const idempotent = !init.method || ["GET", "HEAD", "PUT", "DELETE"].includes(init.method);
  let wait = 300;
  for (let attempt = 1; ; attempt++) {
    const last = attempt >= tries || !idempotent;
    try {
      const res = await fetch(url, init);
      if (res.ok || res.status < 500 || last) return res;
    } catch (err) {
      if (last || (err instanceof Error && err.name === "AbortError")) throw err;
    }
    await new Promise((resolve) => setTimeout(resolve, wait));
    wait *= 2;
  }
}

A cache with stale-while-revalidate and in-flight deduplication. It caches GETs only, treats entries as stale after 30 seconds (a constant, deliberately "not a knob"), serves the last good data if a refresh fails, and lets mutations invalidate by URL prefix, so PATCH /api/tasks/{id} invalidates /api/tasks:

async function cached<T>(url: string, init: RequestInit = {}): Promise<T> {
  const method = init.method ?? "GET";
  const key = `${method} ${url}`;
  if (method !== "GET") return read<T>(url, init);
  const hit = GUML_CACHE.get(key);
  const fresh = hit && Date.now() - hit.at < GUML_STALE_MS;
  if (hit && !fresh) {
    void refresh<T>(key, url, init).catch(() => {});
  }
  if (hit) return hit.data as T;
  const pending = GUML_INFLIGHT.get(key);
  if (pending) return pending as Promise<T>;
  return refresh<T>(key, url, init);
}

A list fetch that can be cancelled, with an alive guard so a late response never writes into an unmounted component:

const tasksList = useCallback(() => {
  const controller = new AbortController();
  let alive = true;
  setTasksLoading(true);
  setTasksError(null);
  cached<Task[]>("/api/tasks", { signal: controller.signal })
    .then((rows) => { if (alive) setTasks(rows); })
    .catch((err: unknown) => {
      if (!alive || (err instanceof Error && err.name === "AbortError")) return;
      setTasksError(err instanceof Error ? err.message : "Unknown error");
    })
    .finally(() => { if (alive) setTasksLoading(false); });
  return () => { alive = false; controller.abort(); };
}, []);

And the optimistic update with rollback, all from the word optimistic:prepend:

const tasksAdd = useCallback(
  async (body: Partial<Task>) => {
    const snapshot = tasks;
    setTasksSaving(true);
    const optimistic = { id: `tmp-${Date.now()}`, ...body } as Task;
    setTasks((prev) => [optimistic, ...prev]);
    try {
      const res = await retrying("/api/tasks", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
      });
      if (!res.ok) throw new Error(`Request failed: ${res.status}`);
      invalidate("/api/tasks");
      const created = (await res.json()) as Task;
      setTasks((prev) => prev.map((it) => (it === optimistic ? created : it)));
    } catch (err: unknown) {
      setTasks(snapshot);
      setTasksError(err instanceof Error ? err.message : "Could not save");
    } finally {
      setTasksSaving(false);
    }
  },
  [tasks],
);

Diagram from the original.

Here's that state machine running. Rows appear instantly with a tmp- id. When the server answers, they either become real or vanish. Click to change the failure rate:

A frame from the interactive sketch in the original — it does not render here.

Leave it at 70% for a while and you'll spot a subtle thing. When two adds overlap and the first fails, the rollback restores the first one's snapshot, so the second row disappears too, even if it later succeeds. The generated React has the same property, because snapshot is captured per call. It's on my list.

Two smaller niceties: the tasksSaving flag only exists if some busy= reads it, and it clears in finally, "or one failed mutation leaves the button saying 'Adding…' forever". And an error boundary is only emitted when the document uses an escape hatch, since generated code can't throw in ways the compiler didn't write.

Seven backends, one vocabulary

The same 24 lines through every backend:

Backend	`--backend`	Lines for b.guml	What it's for
React + TS	`react`	253	the default; ~85 lines are the inlined runtime
React, shared runtime	`react --runtime shared`	171 + 95	one runtime module across pages, so invalidation holds across them
Svelte 5	`svelte`	202	runes
Web Components	`wc`	267	no framework, no build step
Static HTML	`html`	297	mostly the inlined stylesheet
JSON UI tree	`json`	274	for your own renderer; the playground preview uses it
A2UI	`a2ui`	240	Google's agent-UI wire format, "a2ui-shaped"
MCP-UI	`mcp-ui`	13	one JSON resource embedding the wc script

The design goal is that backends share decisions rather than copy them: one element table (element_for(tag)), one design-system table (theme::active().classes(tag, mods)), one expression lowering (expr::lower_in) and one liveness answer (referenced_names, which deliberately over-approximates so codegen never drops a declaration the output still mentions).

The element table exists because of a bug. The HTML backend once had a fallback of _ => "div", so the no-JavaScript build had no landmarks. Now a test checks that every tag lowers to the same element in every backend.

The A2UI emitter is labelled honestly: it was "written from a description of the protocol rather than against its published JSON schema". Actions become declared intents, so no JavaScript travels in the payload.

Themes and capabilities

A theme is data, with a contract

There are no class strings in GUML source, so all presentation comes from a theme. A theme is JSON: rules mapping (tag, modifiers) to classes, plus a contract the compiler enforces. From crates/guml-codegen/src/theme.rs:

pub fn validate(&self) -> Result<(), ThemeError> {
    if self.contract.focus_visible.trim().is_empty() {
        return Err(ThemeError::WeakContract(format!(
            "theme `{}` declares no `contract.focus_visible`; a control nobody can see focus on \
             is unusable from a keyboard, and the compiler cannot supply one it does not know", self.name)));
    }
    if self.contract.min_contrast < 4.5 {
        return Err(ThemeError::WeakContract(format!(
            "theme `{}` declares `min_contrast` {}, below the WCAG AA floor of 4.5 for body text", ...)));
    }
    Ok(())
}

The compiler appends the contract's focus and disabled classes to every focusable element itself, "so a theme cannot forget it on one control". That's what lets a themeable compiler still promise accessible output. Two themes are built in: stock tailwind (the default) and shadcn, which uses shadcn/ui's own oklch tokens, so a host already running shadcn drops it in unchanged.

What will this document do?

If a model writes your UI, you want to know what it can do before you render it. guml capabilities walks the AST and tells you. Real output over the fixtures:

fixtures\b.guml — Tasks (app)
  network: self
    GET    /api/tasks (tasks)
    POST   /api/tasks (tasks.add)  mutating
    PATCH  /api/tasks/{id} (tasks.save)  mutating
    DELETE /api/tasks/{id} (tasks.drop)  mutating
  component `tabs` needs a runtime
  component `list` needs a runtime
fixtures\c.guml — Landing (core)
  inert: no script, no network, markup only
fixtures\d.guml — Spend (app)
  script: a `js` block runs code the compiler does not check
  raw: host markup the compiler does not escape
  escape hatches: 3 (10.7% of lines)

It also derives a Content-Security-Policy from that manifest, so the browser enforces what the compiler found:

$ guml capabilities fixtures/b.guml --csp react
default-src 'none'; connect-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; form-action 'none'; frame-ancestors 'none'; base-uri 'none'

Diagram from the original.

What is measured, and what is not

This project is a study before it's a language, and the repo is unusually strict about labelling claims. I'll keep the same discipline here, because it's easy to overclaim in this space.

Measured: authored fixtures, a real tokenizer

These are hand-written GUML and hand-written React for the same three apps, counted with cl100k_base:

Fixture	React + TS + Tailwind	GUML	Reduction	Ratio
Counter card	368	64	82.6%	5.8×
Task CRUD	1,434	173	87.9%	8.3×
Landing page	1,648	376	77.2%	4.4×
Total	3,450	613	82.2%	5.6×

o200k_base agrees within a percentage point. The Task CRUD row has a story. It was first published as 175 tokens. A recount said 182, and after guml fmt removed 12 bytes of padding it's 173. The research report says so in a correction box: "the original figure was wrong by 7 tokens and no one caught it, which is exactly the failure this project accuses other people's headline claims of." The culprit was Windows Python reading stdin in the console codepage, which mangled the … character.

The obvious objection is "why not just emit JSON?", so that was measured too. Minified JSON for the same task app is 315 tokens against GUML's 173, so GUML is 45% smaller.

The content floor

Compression isn't uniform, and the reason is prose. In the landing page, 232 of GUML's 376 tokens are the human copy itself, which costs the same in any language. Structure is only 144 tokens in GUML, against about 1,416 in React. So the ratio follows a simple curve:

$$
r(P) = \frac{S_{\text{React}} + P}{S_{\text{GUML}} + P}, \qquad r(0) = \frac{1416}{144} \approx 9.8\times, \qquad \lim_{P \to \infty} r(P) = 1
$$

Drag across it:

A frame from the interactive sketch in the original — it does not render here.

Structure-heavy screens approach 8–10×, and content-heavy ones settle toward 2–3×. In the report's words: "Any benchmark that reports a single average number is misleading." The benchmark harness takes that literally and has no code path that prints an overall average.

Measured: GUML against its own compiler output

The README's headline 7.8× is a different measurement, so it gets its own label. scripts/measure.mjs compiles every fixture and divides the size of the emitted React by the size of the GUML. That needs no second author, because nobody wrote the right-hand side. It uses a 3.6 characters-per-token estimate, not a tokenizer. My run:

  fixture        guml    emitted   ratio   vs hand-written
  ----------------------------------------------------------
  a.guml            67       476    7.1×     5.8×
  b.guml           183      2907   15.9×     8.8×
  c.guml           420      1823    4.3×     4.2×
  d.guml           203      2597   12.8×        —
  e.guml           604      4434    7.3×        —
  invoices.guml    211      3087   14.6×        —
  portfolio.guml  1039      5866    5.6×        —
  ----------------------------------------------------------
  total           2727     21190    7.8×

The script prints its own caveat: the ratio rises when the compiler generates more code. b.guml reads 15.9× here because the compiler now emits a cache layer a human wouldn't write, so 15.9× and the 8.3× above must never be quoted together.

Measured: the cost of a change

First drafts aren't where the time goes. bench/guml-bench/edit-locality.mjs scripts eight real modifications and compares the smallest unified diff in each language. That's the fair baseline, diff-based editing, not regeneration. Hover the bars:

Chart from the original.

The median over the seven comparable edits is 5.5×. The eighth edit, add a loading state, isn't in the chart because it costs zero tokens in GUML (a resource's loading state is generated from its declaration) against 67 in React. And again the caveat that ships with the script: it's 8 scripted modifications, where the report specifies 50 tasks × 3. It's a seed set, not a publishable sample.

Not measured

Whether a model can produce correct GUML, and whether that's better or worse than producing React. That's the actual research question, and it's still open. More on it below.

A real model tried it

There's one exploratory run with a real model, and it's reported because a negative result is worth reporting. Six small apps were generated by Llama 3.1 8B Instruct on build.nvidia.com, with the shipping prompt (about 3,073 estimated tokens), temperature 0.2, one generation each:

App	Parses	Requirements met	First error
todo	yes	8 / 8	—
expenses	no	6 / 6	GUML0030 unknown tag `option`
bmi	no	5 / 6	GUML0020 trailing prose
dashboard	no	5 / 6	GUML0033 undeclared `order`
signup	no	5 / 6	GUML0030 `option`
tip	no	3 / 5	GUML0030 unknown tag `---`

1 of 6 parsed, but 32 of 37 functional requirements were met. The findings file says it best: "The gap between those two numbers is the finding." The model understood the apps: the right resources, mutations, aggregates, enumerated filters and disabled bindings. It failed on surface rules.

Then the interesting part. Two of those failures were the compiler refusing information it already had. A select with option children was rejected even though codegen already accepted that spelling, and a field's accessible name was sitting in the binding next to it. After fixing both, the same six generations went from 1 of 6 compiling to 3 of 6, with no regeneration: identical model output, and a compiler that stopped saying no.

The two that still fail are GUML0023, the expression language: **, and orders.where(status=new).count. That's what a model reaches for and the parser doesn't cover yet. One more humbling number: of nine model-driven repair attempts, seven did no better than the free layers, and two made things worse. A remarkable bonus is that todo.guml independently reproduced the shape of the hand-written task fixture from a prompt that never mentioned it.

The playground and the chat

The docs site is a Next.js app, and everything interactive on it runs the real compiler as WebAssembly in your tab. The playground shows real diagnostics, a format button, and an "emitted React" pane that is byte-for-byte what guml build writes:

The preview is rendered from the compiler's own JSON UI tree, never by eval, so it can't drift from the code.

The /chat page closes the loop: describe an interface, a hosted model answers in GUML, and the compiler renders it in the tab. The free repair layers run on the answer, and the page tells you what they changed. The prompt-tax meter is honest too, at about 3,713 estimated tokens, and the system prompt is generated from the same file the Phase 0 experiment uses: "A product that prompts differently from the experiment makes the experiment decorative."

For agents there's an MCP server, guml mcp, with five tools: guml_registry, guml_spec, guml_check, guml_repair and guml_compile. A prompt can carry a vocabulary, but it can't tell a model whether what it just wrote is correct. That needs the compiler:

→ guml_check(source)    DOES NOT COMPILE — 1 error(s). Fix these and check again.
                        error [GUML0030] line 4: unknown tag `crad`
                            help: did you mean `card`?
                            replace with: card

Proof: what I ran for this post

I didn't want to restate README numbers, so I re-ran what I could on a clean checkout of main (4418bc5):

Claim	How I checked	Result
561 Rust tests	`cargo test --workspace`	561 passed, 0 failed, 1 ignored
49 diagnostic codes	counted from `guml explain`	49
61 conformance cases	counted the cases in `spec/tests/*.txt`	15 + 30 + 7 + 9 = 61
7.8× vs emitted React	`node scripts/measure.mjs`	7.8×, output above
Edit locality	`node bench/guml-bench/edit-locality.mjs`	median 5.50× over 7 edits
One-pass diagnostics	`guml check broken.guml`	3 errors from 3 passes, output above
Free repair	`guml repair --format json`	7 → 2 errors, no model call
Playground, chat, emitted React	local docs site + headless Chrome	the screenshots in this post

Not re-run by me: the 1,000,000-document fuzz run (the one ignored test), the mutation study (1,031 definitionally invalid mutants, 95.5% detected), and anything needing an API key.

What I found while writing this

Same rule as every project post: if I find something while writing, it goes in. GUML's own invariant is "a quietly wrong compiler destroys the reliability claim the whole project rests on", so these matter more here than they would elsewhere.

1. "Apply 3 fixes" deletes a line

Click apply 3 fixes on the playground's broken sample and you get this:

metric {kount} became the bare word count, which is now an unknown tag. Remember those carets? GUML0033's span covers the whole element, but its suggestion is just the identifier. The Rust applier already knows about this failure mode and refuses it. From crates/guml-compiler/src/fix.rs:

/// A suggestion replaces its span, so a bare word attached to a whole-line span replaces the
/// line with that word. [...] the failure mode is silent data loss, so the applier checks
/// rather than trusts: if the span covers whitespace, the replacement has to as well.
fn spans_one_token(span_text: &str, replacement: &str) -> bool {
    !span_text.contains(char::is_whitespace) || replacement.contains(char::is_whitespace)
}

The TypeScript twin in @guml/core, which the playground and the chat page both call, doesn't have that guard:

export function applySuggestion(source: string, d: Diagnostic): string {
  if (!d.suggestion || !isApplicable(d)) return source;
  return source.slice(0, d.span.start) + d.suggestion + source.slice(d.span.end);
}

Also, the button counts every diagnostic with a suggestion, including the aria="…" template it then correctly skips, so it says "3 fixes" and applies 2. The fix is small: port spans_one_token to TypeScript, count only applicable suggestions, and ideally narrow GUML0033's span to the identifier. The lesson is bigger: two implementations of one policy drift, and the test that would catch it is a parity test over the same inputs.

2. Web Components: Delete changes the filter

In the wc output for the task app, top-level actions and row actions are numbered independently, both starting at 0. So the row's Delete button carries data-g-act="1", which is exactly the case "click:1" that sets the filter to all. The row checkbox carries data-g-act="0", which only has a submit:0 case. Clicking Delete changes the filter, and ticking a task does nothing. The existing test compares sets of action indices, and the collision makes those sets equal, so it passes. MCP-UI embeds the same script, so it inherits the bug.

3. Svelte: new tasks are posted empty

The Svelte backend emits async function tasksAdd(item, body = {}) for every mutation, but the form calls tasksAdd({ title: draft }). The object lands in item, so the POST body is {}.

4. `raw html` passes the "inert" gate

core is described as "safe to render from an untrusted agent", and --assert-inert as the gate for that. But this document passes both --core and --assert-inert, and the HTML backend emits the handler verbatim:

page P
raw html
  <img src=x onerror=alert(1)>
p Hi

The parser rejects js at the core level but not raw, and is_inert() ignores the raw_markup flag the manifest already computes. The derived CSP would block the inline handler, but only if the host actually sends it. I'd fix this one first.

5. Docs drift

The README says shadcn/ui is the default theme; the code defaults to stock Tailwind.
The committed wasm is 861 KB, not the 787 KB the README and playground quote.
The docs home page says "396 tests" and the architecture page "552 tests"; the suite has 561.

The repo already has check-readme-claims.mjs to stop exactly this, and these are the claims it doesn't cover yet.

None of this changes the argument, and all of it was found by running the thing rather than reading it, which is the project's own philosophy. React is the backend that's exercised by typecheck and render tests, and it's the one that held up. The others need the same harness pointed at them.

The question still open

Everything above is the instrument. The research report is blunt about what the language itself contributes: "the language is not novel. The measurement, the crossover characterization, and the convention-as-correctness-guarantee framing are."

The tension is real. A DSL cuts output tokens and narrows what a model can get wrong, but it also moves the model off-distribution. GUML has zero training data by construction, and the low-resource-language literature consistently reports accuracy drops. Against that, Anka (arXiv:2512.23214) reports a constrained DSL beating Python by 40 points on multi-step tasks, in one narrow domain. Nobody has characterised where the crossover is.

So the report pre-registers six hypotheses: validity, correctness ("the crux hypothesis. If H2 fails, the project is a cost optimization, not a research contribution"), hallucination, consistency, the accessibility floor, and a capability threshold. The last one predicts GUML helps small models most and may invert on frontier models.

And it defines a two-week kill-or-continue experiment, Phase 0:

Diagram from the original.

Status, verbatim from the repo: "not yet run. The gate is undecided." Everything the experiment needs is built and runs in CI: the ten tasks, ten React references that typecheck under --strict, prompt assembly, scoring, and a blind scoresheet. An attempt with a valid key returned Your credit balance is too low, so zero of the 90 generations have run. What's missing is the answer, not the instrument.

What I learned

Diagnostics are the product. In a generation loop, an error message is an API: a code, a span and a replacement. "Every error in one pass" saves real money, and "append-only codes" is a compatibility promise like any other.
Moving work into the compiler moves bugs into the compiler. That's a good trade, because a compiler bug is fixed once for every generation. But it raises the bar: a silently wrong backend is worse than a loud model error.
Two implementations of one rule will drift. Rust and TypeScript fix appliers, seven backends, a README and a docs site. Every drift I found was between two copies of the same decision.
Compression has a floor, and it's prose. You can't compress the words a human has to read. Any single average ratio hides that.
The honest number is the interesting one. 1 of 6 parsing, but 32 of 37 requirements met, taught me more than any compression figure, because it says exactly where the compiler, not the model, was the problem.
Measure the thing that's fair, not the thing that flatters. Diff-based edits instead of regeneration, the compiler's own output instead of a second author, and a correction box when a number was wrong.

What's next

Fix the five findings above, starting with the raw inert gate, then port spans_one_token to @guml/core with a parity test.
Point the typecheck and render harness at Svelte and Web Components, not just React. The wc collision would have been one click away from being caught.
Grow the expression language where models actually reach: **, ternaries, and .where(...) aggregates (GUML0023).
Playwright, axe and Lighthouse over the emitted output. Today it's proven to typecheck and server-render, not proven to work when clicked. That's the largest gap in what's verified.
Run Phase 0. 90 generations, three models, a blind grader. Then publish whichever answer comes back.

Try it

git clone https://github.com/ravikisha/guml && cd guml
cargo test --workspace

cargo run -q -p guml-cli -- build fixtures/b.guml                   # React + TS
cargo run -q -p guml-cli -- build fixtures/b.guml --backend svelte
cargo run -q -p guml-cli -- check fixtures/invoices.guml --format json
cargo run -q -p guml-cli -- capabilities fixtures
cargo run -q -p guml-cli -- explain GUML0050

# what a model actually returns, repaired with no model call:
printf 'Here you go:\n\n```

guml\npage P\ndiv\n  span Hi\n

```\n' | cargo run -q -p guml-cli -- repair

node scripts/measure.mjs                    # the 7.8× table
node bench/guml-bench/edit-locality.mjs     # the cost of a change

Or give your agent the compiler instead of a prompt:

{ "mcpServers": { "guml": { "command": "guml", "args": ["mcp"] } } }

If you've read my posts on RelaxLang (a language) and Relaxnative (Rust from Node), GUML is where those two threads meet: a language whose user is a model, and a Rust compiler that ships to the browser as WebAssembly.

⭐ Star it on GitHub. If you have API credit and want to help answer the question this project exists for, the Phase 0 harness is waiting. And if you find a document where the compiler is quietly wrong, open an issue. Those are the bugs that matter most here.

Happy compiling! 🦀

10 Algorithm Patterns That Crack Most Coding Problems, Visualized

Ravi Kishan — Fri, 16 Oct 2026 04:51:52 +0000

TL;DR: Most coding problems are not new problems. They are one of about ten patterns wearing a costume. This post covers the ten I reach for most often. For each one you get the signals that give it away, an interactive visualization of it running, a classic problem with a tested Python solution, and why it works, with the complexity.

Every sketch is live: watch it run, then click it to get fresh input.

Why patterns beat memorising problems
Which pattern? A cheat sheet
Pattern 1: Two pointers
Pattern 2: Sliding window
Pattern 3: Fast and slow pointers
Pattern 4: Prefix sum and hash map
Pattern 5: Binary search on the answer
Pattern 6: Monotonic stack
Pattern 7: BFS by levels
Pattern 8: Backtracking
Pattern 9: Top K with a heap
Pattern 10: Dynamic programming
Complexity at a glance
Honourable mentions
How to practise

Why patterns beat memorising problems

There are thousands of problems on LeetCode and only a handful of ideas underneath them. "Longest substring without repeating characters", "minimum window substring" and "max consecutive ones III" look different, but they are the same algorithm: a window that grows on the right and shrinks on the left.

So the useful skill isn't remembering 500 solutions. It's reading a problem statement and noticing the signal: contiguous, sorted, k-th largest, all combinations, minimum number of steps. Each one points at a pattern, and each pattern comes with a template you've already debugged.

Every pattern below follows the same shape:

Signals: the words in a problem that should make you think of it.
The idea: the one insight that makes it work.
Visualization: a live sketch you can click.
Sample problem: a classic, with a Python solution.
Why it's correct and how fast it is.

All ten sample solutions in this post were run against LeetCode's own examples and thousands of random inputs checked by brute force, so you can trust them as templates.

Which pattern? A cheat sheet

Diagram from the original.

Pattern 1: Two pointers

Signals: the array is sorted, and you're looking for a pair (or triplet) that meets a target. Also: reversing in place, partitioning, or merging two sorted arrays.

The idea: put one pointer at each end. Because the array is sorted, comparing the current sum with the target tells you exactly which pointer to move. If the sum is too small, only moving the left pointer right can make it bigger. If it's too big, only moving the right pointer left can shrink it. Every comparison throws away one element for good, which turns an O(n²) pair search into O(n).

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Two Sum II (LeetCode 167)

Given a 1-indexed, sorted array numbers and a target, return the indices of the two numbers that add up to target. Exactly one solution exists, and you may not use the same element twice.

numbers = [2, 7, 11, 15], target = 9 → [1, 2]

def two_sum(numbers, target):
    lo, hi = 0, len(numbers) - 1
    while lo < hi:
        s = numbers[lo] + numbers[hi]
        if s == target:
            return [lo + 1, hi + 1]  # the problem is 1-indexed
        if s < target:
            lo += 1  # need a bigger sum: only lo can grow it
        else:
            hi -= 1  # need a smaller sum: only hi can shrink it
    return []

Why it's correct: when numbers[lo] + numbers[hi] < target, pairing numbers[lo] with any element left of hi gives an even smaller sum, so numbers[lo] can't be in the answer. Discarding it is safe. The same argument mirrors for hi. O(n) time, O(1) space.

Practise: 3Sum (15), Container With Most Water (11), Valid Palindrome (125).

Pattern 2: Sliding window

Signals: contiguous subarray or substring, plus longest, shortest, at most k, or without repeating.

The idea: keep a window [L, R) that is always valid. Grow it on the right. When adding a character breaks the rule, shrink it from the left until it's valid again. Both pointers only ever move right, so the total work is linear, even though there's a loop inside a loop.

A frame from the interactive sketch in the original.

Sample problem: Longest Substring Without Repeating Characters (LeetCode 3)

Given a string s, find the length of the longest substring without repeating characters.

"abcabcbb" → 3 ("abc"), "pwwkew" → 3 ("wke")

The sketch shrinks one character at a time to make the idea visible. In real code you can jump L straight past the duplicate by remembering where you last saw each character:

def length_of_longest_substring(s):
    last = {}  # char -> index where we last saw it
    best = left = 0
    for right, ch in enumerate(s):
        if ch in last and last[ch] >= left:
            left = last[ch] + 1  # jump past the duplicate in one move
        last[ch] = right
        best = max(best, right - left + 1)
    return best

Why it's linear: each index enters the window once (when right reaches it) and leaves at most once (when left passes it). That's at most $2 n$ pointer moves in total, so O(n) time, and O(alphabet) space for the map.

Practise: Minimum Window Substring (76), Longest Repeating Character Replacement (424), Max Consecutive Ones III (1004).

Pattern 3: Fast and slow pointers

Signals: a linked list (or anything with a next function) where you need to find a cycle, where it starts, or the middle, using O(1) extra memory.

The idea: move a slow pointer one step at a time and a fast pointer two. If there's no cycle, fast falls off the end. If there is one, fast gains one node per step inside the cycle, so it must eventually land on slow. That's Floyd's algorithm. The clever bit is phase 2: put one pointer back at the head, move both one step at a time, and they meet exactly where the cycle begins.

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Linked List Cycle II (LeetCode 142)

Given the head of a linked list, return the node where the cycle begins, or None if there is no cycle. Use O(1) memory.

def detect_cycle(head):
    slow = fast = head
    while fast and fast.next:
        slow, fast = slow.next, fast.next.next
        if slow is fast:  # phase 1: they met somewhere inside the cycle
            slow = head  # phase 2: one pointer back to the head
            while slow is not fast:
                slow, fast = slow.next, fast.next
            return slow  # where they meet again is the cycle's entry
    return None

Why phase 2 works: say the tail has $μ$ nodes, the cycle has $λ$ , and they meet $a$ steps past the cycle's entry. Slow walked $μ + a$ steps and fast walked twice that. The extra distance fast covered is whole laps of the cycle:

$$
2(\mu + a) - (\mu + a) = \mu + a = m\lambda \quad\Longrightarrow\quad \mu = m\lambda - a
$$

So walking $μ$ more steps from the meeting point is $m$ full laps minus $a$ , which lands exactly on the entry. A pointer walking $μ$ steps from the head lands there too. O(n) time, O(1) space.

Practise: Middle of the Linked List (876), Happy Number (202), Find the Duplicate Number (287).

Pattern 4: Prefix sum and hash map

Signals: count (or find) subarrays whose sum equals k, especially when the array has negative numbers. Sliding window breaks here, because adding a negative can shrink a sum, so a window can't know which way to move.

The idea: a running prefix sum turns "sum of a range" into "difference of two prefixes":

$$
\text{sum}(i..j) = P_j - P_{i-1} = k \quad\Longleftrightarrow\quad P_{i-1} = P_j - k
$$

So as you scan, the number of subarrays ending at j with sum k is just how many earlier prefixes equal $P_{j} - k$ . A hash map of prefix counts answers that in O(1).

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Subarray Sum Equals K (LeetCode 560)

Given an integer array nums (which may contain negatives) and an integer k, return the total number of contiguous subarrays whose sum equals k.

nums = [1, 1, 1], k = 2 → 2

from collections import defaultdict

def subarray_sum(nums, k):
    seen = defaultdict(int)
    seen[0] = 1  # the empty prefix: lets a subarray start at index 0
    prefix = count = 0
    for x in nums:
        prefix += x
        count += seen[prefix - k]  # every earlier prefix p with prefix - p == k
        seen[prefix] += 1
    return count

The one line people forget is seen[0] = 1. Without it, a subarray that starts at index 0 has no earlier prefix to match against and is never counted. O(n) time, O(n) space.

Practise: Continuous Subarray Sum (523), Contiguous Array (525), Range Sum Query: Immutable (303).

Pattern 5: Binary search on the answer

Signals: a sorted array, obviously. But also, and more usefully: find the **minimum* speed, capacity, or size such that something is possible*. If a value works and every larger value also works, the answer space is monotonic, and you can binary search it even though nothing is sorted.

The idea: every binary search is really one question: where does a boolean flip from false to true? Write feasible(x), then shrink [lo, hi] by half each step until lo == hi. That's at most $⌈ lo g_{2} n ⌉$ probes instead of $n$ .

In the sketch, each cell is a candidate eating speed k. Red means too slow and green means fast enough. You never need to check most of them:

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Koko Eating Bananas (LeetCode 875)

Koko has piles of bananas and h hours. Each hour she picks one pile and eats k bananas from it (or the whole pile if it has fewer). Return the minimum integer k that lets her finish within h hours.

piles = [3, 6, 7, 11], h = 8 → 4

def min_eating_speed(piles, h):
    def hours(k):
        return sum((p + k - 1) // k for p in piles)  # ceil without floats

    lo, hi = 1, max(piles)
    while lo < hi:
        mid = (lo + hi) // 2
        if hours(mid) <= h:
            hi = mid  # mid works: the answer is mid or smaller
        else:
            lo = mid + 1  # mid is too slow: the answer is bigger
    return lo

Why it's correct: $hours (k) = \sum_{i} ⌈ p_{i} / k ⌉$ can only go down as $k$ goes up, so feasible is false, false, …, true, true. The loop keeps the first true inside [lo, hi] at every step. O(n log m) time, where m is the largest pile.

The template to memorise is the lo < hi, hi = mid / lo = mid + 1 form. It never loops forever and it always lands on the first true.

Practise: Capacity To Ship Packages Within D Days (1011), Search in Rotated Sorted Array (33), Split Array Largest Sum (410).

Pattern 6: Monotonic stack

Signals: the next greater element, the next smaller element, how many days until warmer, the largest rectangle. Anything that asks each element about the nearest element to its right (or left) that beats it.

The idea: keep a stack of indices that are still waiting for an answer. Their values are always in decreasing order, which is what makes it "monotonic". When a new element is bigger than the top of the stack, it is the answer for the top, so pop it and record the distance. Keep popping while it's still bigger, then push the new element so it can wait too.

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Daily Temperatures (LeetCode 739)

Given daily temperatures, return an array where answer[i] is the number of days after day i until a warmer temperature, or 0 if there is none.

[73, 74, 75, 71, 69, 72, 76, 73] → [1, 1, 4, 2, 1, 1, 0, 0]

def daily_temperatures(temps):
    ans = [0] * len(temps)
    stack = []  # indices still waiting, temperatures decreasing
    for i, t in enumerate(temps):
        while stack and temps[stack[-1]] < t:
            j = stack.pop()
            ans[j] = i - j
        stack.append(i)
    return ans

Why it's O(n): there's a while inside a for, but every index is pushed once and popped at most once. That's at most $2 n$ stack operations in total, so O(n) time, O(n) space, instead of the O(n²) "scan right from every day" approach.

Practise: Next Greater Element I (496), Largest Rectangle in Histogram (84), Online Stock Span (901).

Pattern 7: BFS by levels

Signals: the fewest steps, minimum moves or shortest path in a grid or a graph where every edge costs the same. Also anything that spreads one ring at a time: fire, infection, rotting.

The idea: a queue processes nodes in order of distance. Process the queue one whole level at a time (for _ in range(len(q))) and the level counter is the distance. Several starting points? Put them all in the queue at the start. That's a multi-source BFS, and it costs nothing extra.

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Rotting Oranges (LeetCode 994)

In a grid, 0 is empty, 1 is a fresh orange and 2 is a rotten one. Every minute, each fresh orange next to a rotten one (up, down, left or right) becomes rotten. Return the minutes until no fresh orange is left, or -1 if that's impossible.

[[2,1,1],[1,1,0],[0,1,1]] → 4

from collections import deque

def oranges_rotting(grid):
    rows, cols = len(grid), len(grid[0])
    q, fresh = deque(), 0
    for r in range(rows):
        for c in range(cols):
            if grid[r][c] == 2:
                q.append((r, c))  # every source starts in the queue
            elif grid[r][c] == 1:
                fresh += 1
    minutes = 0
    while q and fresh:
        for _ in range(len(q)):  # one whole BFS level = one minute
            r, c = q.popleft()
            for nr, nc in ((r + 1, c), (r - 1, c), (r, c + 1), (r, c - 1)):
                if 0 <= nr < rows and 0 <= nc < cols and grid[nr][nc] == 1:
                    grid[nr][nc] = 2
                    fresh -= 1
                    q.append((nr, nc))
        minutes += 1
    return -1 if fresh else minutes

Why BFS and not DFS: DFS dives down one path and finds a path, not the shortest one. BFS visits everything at distance 1 before anything at distance 2, so the first time it reaches a cell is via a shortest path. O(rows × cols) time and space.

Practise: Number of Islands (200), Shortest Path in Binary Matrix (1091), Word Ladder (127).

Pattern 8: Backtracking

Signals: return all subsets, permutations, combinations or partitions; place N queens; solve a sudoku. Any problem where the answer is every valid arrangement rather than a count of them.

The idea: every answer is a sequence of choices, so the search space is a decision tree. Walk it depth-first with one shared path: choose (append), recurse, un-choose (pop). The un-choose step is the "backtrack". It restores the state so the sibling branch starts clean. Pruning, i.e. skipping branches that can't lead to a valid answer, is what makes the harder versions fast.

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Subsets (LeetCode 78)

Given an array of unique integers nums, return all possible subsets (the power set), in any order.

[1, 2, 3] → [[1,2,3], [1,2], [1,3], [1], [2,3], [2], [3], []]

def subsets(nums):
    out, path = [], []

    def dfs(i):
        if i == len(nums):
            out.append(path[:])  # a leaf: record a copy
            return
        path.append(nums[i])  # choose
        dfs(i + 1)
        path.pop()  # un-choose
        dfs(i + 1)  # skip

    dfs(0)
    return out

Note the path[:]. Appending path itself would store the same list object eight times, and since it ends empty, you'd get eight empty lists. O(n · 2ⁿ) time: there are $2^{n}$ subsets and copying each costs up to $n$ . That's optimal, because the output itself is that big.

Practise: Permutations (46), Combination Sum (39), N-Queens (51).

Pattern 9: Top K with a heap

Signals: the k-th largest or smallest, the top k frequent, the k closest points, or a median of a stream. Anything that needs the best few without fully sorting.

The idea: to keep the k largest, use a min-heap of size k. Its root is the smallest of the k largest, which is exactly the k-th largest. A new number only matters if it beats the root: if it does, evict the root and push the new one; if not, ignore it. The direction feels backwards the first time: largest needs a min-heap, because the root is the gatekeeper.

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Kth Largest Element in an Array (LeetCode 215)

Given an integer array nums and an integer k, return the k-th largest element (in sorted order, not the k-th distinct one).

nums = [3, 2, 1, 5, 6, 4], k = 2 → 5

import heapq

def find_kth_largest(nums, k):
    heap = []  # min-heap of the k largest so far
    for x in nums:
        if len(heap) < k:
            heapq.heappush(heap, x)
        elif x > heap[0]:
            heapq.heapreplace(heap, x)  # pop the smallest, push x
    return heap[0]

Why it beats sorting: sorting is O(n log n). The heap never holds more than k items, so each push or replace costs O(log k), for O(n log k) time and O(k) space. When k is small and n is huge, or the data is a stream you can't sort at all, that difference is the whole point.

Practise: Top K Frequent Elements (347), K Closest Points to Origin (973), Find Median from Data Stream (295).

Pattern 10: Dynamic programming

Signals: the fewest, the most, or the number of ways, where a choice now leaves a smaller version of the same problem, and those smaller problems overlap (the naive recursion keeps solving the same one again).

The idea: define what one cell means, in plain words, before writing any code. Here, dp[x] is the fewest coins that make x. Then write how a cell is built from smaller ones, and fill the table in an order where those smaller cells already exist:

$$
dp[0] = 0, \qquad dp[x] = 1 + \min_{c \,\in\, \text{coins},\ c \le x} dp[x - c]
$$

Watch each cell try every coin, look back at an earlier cell (the arc) and keep the best. When it finishes, the green arcs below trace the coins actually used:

A frame from the interactive sketch in the original — it does not render here.

Sample problem: Coin Change (LeetCode 322)

Given coin denominations coins and an amount, return the fewest coins that make up that amount, or -1 if it can't be done. You have unlimited coins of each kind.

coins = [1, 2, 5], amount = 11 → 3 (5 + 5 + 1)

def coin_change(coins, amount):
    INF = amount + 1  # more coins than could ever be needed
    dp = [0] + [INF] * amount  # dp[x] = fewest coins that make x
    for x in range(1, amount + 1):
        for c in coins:
            if c <= x:
                dp[x] = min(dp[x], dp[x - c] + 1)
    return dp[amount] if dp[amount] != INF else -1

Why not just be greedy? With coins [1, 3, 4] and amount 6, greedy grabs the biggest coin first: 4 + 1 + 1, three coins. The real answer is 3 + 3, two coins. Greedy decides too early. DP tries every last coin and keeps the best, so it can't be fooled. The sketch prints the greedy count whenever greedy would have lost; click until coins [1, 3, 4] come up. O(amount × coins) time, O(amount) space.

Practise: Climbing Stairs (70), House Robber (198), Longest Common Subsequence (1143).

Complexity at a glance

#	Pattern	Classic problem	Time	Extra space
1	Two pointers	Two Sum II (167)	O(n)	O(1)
2	Sliding window	Longest Substring Without Repeating (3)	O(n)	O(alphabet)
3	Fast and slow pointers	Linked List Cycle II (142)	O(n)	O(1)
4	Prefix sum + hash map	Subarray Sum Equals K (560)	O(n)	O(n)
5	Binary search on the answer	Koko Eating Bananas (875)	O(n log m)	O(1)
6	Monotonic stack	Daily Temperatures (739)	O(n)	O(n)
7	BFS by levels	Rotting Oranges (994)	O(rows × cols)	O(rows × cols)
8	Backtracking	Subsets (78)	O(n · 2ⁿ)	O(n) + output
9	Heap (top K)	Kth Largest Element (215)	O(n log k)	O(k)
10	Dynamic programming	Coin Change (322)	O(amount × coins)	O(amount)

Notice how many rows say O(n) where the brute force is O(n²). That's the common thread. Each pattern is a reason why most of the pairs, windows or states you'd naively check can never be the answer, and a way to skip them.

Honourable mentions

Ten covers most problems, but these show up often enough to know by name:

Merge intervals: sort by start, then merge each interval into the last one if they overlap. Merge Intervals (56), Insert Interval (57).
Topological sort: Kahn's algorithm, BFS over in-degrees, for "order these tasks with dependencies". Course Schedule (207).
Union-find: near-O(1) "are these connected?" with path compression. Number of Connected Components (323), Redundant Connection (684).
Trie: a prefix tree for "starts with" and word-search problems. Implement Trie (208).
Two heaps: a max-heap and a min-heap balanced around the middle, for a running median. Find Median from Data Stream (295).
Bit manipulation: XOR tricks, masks and subsets as integers. Single Number (136).

How to practise

Learn the pattern, not the problem. For each pattern, do the sample problem above, then the three practice problems without looking anything up. If they feel like the same problem by the third one, you've got it.
Name the signal before you code. Read the statement and say out loud which word gave it away: "contiguous", "sorted", "k-th", "all combinations", "fewest steps".
Start from the template. Each solution above is small enough to rewrite from memory in a couple of minutes. In an interview, a correct template you trust beats a clever idea you have to debug.
State the complexity and the reason. "O(n), because each index enters and leaves the window once" is the sentence interviewers listen for.
Play with the sketches. Click them until the behaviour stops surprising you. Being able to predict the next step is what understanding feels like.

Happy problem solving! 🧠

Cover photo: "Swiss Army Knife" Abacus by Jccsvq, CC0, via Wikimedia Commons.

RustDNS: Writing a Recursive DNS Resolver in Rust, Byte by Byte

Ravi Kishan — Tue, 06 Oct 2026 15:31:56 +0000

TL;DR: RustDNS is a recursive DNS resolver written in plain Rust with zero dependencies, just std::net::UdpSocket and a 512-byte array. It parses DNS packets by hand, follows compression pointers, starts every lookup at a root server and walks the tree down to the answer, then serves that answer to dig on port 2053. This post goes through the code byte by byte, and then through what broke when I ran it against the real internet.
git clone https://github.com/ravikisha/rustdns && cd rustdns
cargo run --release
🔗 GitHub · 🐛 Issues

Why I built this
DNS in two minutes
Hello, resolver
The map of the code
A 512-byte cursor
Twelve bytes of header
Names, labels and compression pointers
One enum per record type
Walking the tree: recursive resolution
Serving dig on port 2053
Breaking it on purpose
How fast is it?
What I learned
What's next
Try it

Why I built this

Every network request you have ever made started with a question: what is the IP address of this name? You type github.com, and before a single byte of HTML moves, something somewhere has to turn those ten characters into 20.207.73.82.

For years that "something" was a black box to me. I knew the words (resolver, root server, TTL, A record) the way you know the names of planets. I'd never touched one.

The usual analogy is that DNS is the internet's phone book. It's a good analogy, but it hides the interesting part. A phone book is one big printed list. DNS is a distributed phone book: no single machine knows every name, so a resolver has to ask a chain of servers, each of which only knows who to ask next.

I wanted to see that chain with my own eyes, and I wanted to do it in Rust, because DNS is a binary protocol full of bit fields, offsets and length prefixes. That's exactly the kind of code where Rust's Result and bounds checks earn their keep. Malformed packets are not hypothetical on the open internet.

I built RustDNS by working through Emil Hernvall's excellent dnsguide, and if you want a step-by-step tutorial, that guide is the place to go. This post is the other half: a tour of the finished code, plus what happened when I ran it against the real internet two years later.

DNS in two minutes

DNS names are a tree, read right to left. The invisible dot at the end of google.com. is the root. Below it sit the top-level domains (.com, .org, .in), below those the domains people register, and below those whatever names the owner creates.

Diagram from the original.

Each level is delegated. The root servers don't know Google's IP. They only know which servers are in charge of .com. The .com servers don't know it either; they know which servers are in charge of google.com. Only those last servers, the authoritative ones, have the actual answer.

A recursive resolver is the operator in this picture. You ask it one question, and it makes all the calls on your behalf: root, then TLD, then authoritative, then it hands you the answer. Your laptop normally uses one run by your ISP, Google (8.8.8.8) or Cloudflare (1.1.1.1). RustDNS is a tiny one you can run yourself.

Hello, resolver

Build and run it. There are no dependencies to download, so it compiles in seconds:

cargo run --release
# listening on 0.0.0.0:2053 (UDP)

Port 2053 instead of 53 is deliberate: ports below 1024 need root on Linux, and this way you don't have to sudo a learning project. In a second terminal:

dig @127.0.0.1 -p 2053 google.com

No dig on Windows? Neither did I while writing this post, so here is a 12-line client in Python that builds a query packet by hand. It's also a nice preview of the wire format we're about to dissect:

import socket, struct, sys

name, qtype = sys.argv[1], int(sys.argv[2]) if len(sys.argv) > 2 else 1
q = struct.pack(">HHHHHH", 0x1234, 0x0100, 1, 0, 0, 0)   # header: id, flags (RD=1), 1 question
for label in name.split("."):
    q += bytes([len(label)]) + label.encode()             # [6]google[3]com
q += b"\0" + struct.pack(">HH", qtype, 1)                 # end of name, QTYPE, QCLASS=IN

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.settimeout(20)
s.sendto(q, ("127.0.0.1", 2053))
print(s.recvfrom(4096)[0].hex())

The server prints every step of its search. This is a real run from my machine, unedited:

Received query: DnsQuestion { name: "google.com", qtype: A }
attempting lookup of A google.com with ns 198.41.0.4
attempting lookup of A google.com with ns 192.41.162.30
attempting lookup of A google.com with ns 216.239.34.10
Answer: A { domain: "google.com", addr: 142.250.29.100, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.101, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.138, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.113, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.139, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.102, ttl: 300 }

Three lines, three servers: 198.41.0.4 is a.root-servers.net, 192.41.162.30 is l.gtld-servers.net (one of the .com servers), and 216.239.34.10 is ns2.google.com. That's the whole tree from the diagram above, walked in about half a second.

A CNAME chain works too. Asking for www.github.com comes back with an alias and the address it points to:

Answer: CNAME { domain: "www.github.com", host: "github.com", ttl: 3600 }
Answer: A { domain: "github.com", addr: 20.207.73.82, ttl: 60 }
Authority: NS { domain: "github.com", host: "dns1.p08.nsone.net", ttl: 900 }
Authority: NS { domain: "github.com", host: "ns-421.awsdns-52.com", ttl: 900 }
...

So how does it do that?

The map of the code

The whole server lives in one file, src/main.rs, and Cargo.toml has an empty [dependencies] table. It layers neatly from raw bytes up to a running server:

Diagram from the original.

Everything that touches the wire goes through BytePacketBuffer. Everything above it works with plain Rust structs and enums. Let's go bottom-up.

A 512-byte cursor

The original DNS spec (RFC 1035) caps a UDP message at 512 bytes. So the buffer is just a fixed array and a position:

pub struct BytePacketBuffer {
    /// Buffer for holding the packet contents
    pub buf: [u8; 512],
    /// Field for keeping track of where we are
    pub pos: usize,
}

No heap allocation, no Vec, no growing. Reading is a cursor that walks forward and refuses to fall off the end:

fn read(&mut self) -> Result<u8> {
    if self.pos >= 512 {
        return Err("End of the buffer".into());
    }
    let res = self.buf[self.pos];
    self.pos += 1;
    Ok(res)
}

DNS is big-endian ("network byte order"), so multi-byte integers are assembled most-significant byte first:

fn read_u16(&mut self) -> Result<u16> {
    let res = ((self.read()? as u16) << 8) | (self.read()? as u16);
    Ok(res)
}

The ? after every read() is the quiet hero here. A truncated or malicious packet can end at any byte, and every single read propagates that as an error instead of reading garbage. Writing mirrors reading: write_u8, write_u16, write_u32, each splitting the integer back into bytes with shifts.

There are two more primitives that matter later: get(pos) peeks at a byte without moving the cursor, and set_u16(pos, val) overwrites two bytes we already wrote. Hold on to both.

Twelve bytes of header

Every DNS message, query or response, starts with the same 12-byte header:

                                1  1  1  1  1  1
  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                      ID                       |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|QR|   OPCODE  |AA|TC|RD|RA| Z|AD|CD|   RCODE   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    QDCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    ANCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    NSCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    ARCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

Field	Bits	Meaning
`ID`	16	Chosen by the client, copied into the reply so answers can be matched to questions
`QR`	1	0 = query, 1 = response
`OPCODE`	4	0 = standard query
`AA`	1	Authoritative answer: the server owns this name
`TC`	1	Truncated: the answer didn't fit, retry over TCP
`RD` / `RA`	1 + 1	Recursion desired (client asks) / available (server offers)
`AD` / `CD`	1 + 1	DNSSEC: authenticated data / checking disabled
`RCODE`	4	0 NOERROR, 2 SERVFAIL, 3 NXDOMAIN, …
`QDCOUNT` … `ARCOUNT`	16 each	How many entries follow in each of the four sections

The flags live in the middle 16 bits. DnsHeader::read splits them into a high byte a and low byte b and picks them apart with masks:

let flags = buffer.read_u16()?;
let a = (flags >> 8) as u8;
let b = (flags & 0xFF) as u8;
self.recursion_desired    = (a & (1 << 0)) > 0;
self.truncated_message    = (a & (1 << 1)) > 0;
self.authoritative_answer = (a & (1 << 2)) > 0;
self.opcode               = (a >> 3) & 0x0F;
self.response             = (a & (1 << 7)) > 0;

self.rescode              = ResultCode::from_num(b & 0x0F);
self.checking_disabled    = (b & (1 << 4)) > 0;
self.authed_data          = (b & (1 << 5)) > 0;
self.z                    = (b & (1 << 6)) > 0;
self.recursion_available  = (b & (1 << 7)) > 0;

Bit-twiddling is much easier to feel than to read. Click any bit below to flip it and watch the decoded header change. It starts at 0x8180, the flags of a normal successful response: QR, RD and RA set, RCODE 0. Try setting the low bits to 0011 to make an NXDOMAIN.

A frame from the interactive sketch in the original — watch it run.

Writing the header is the same thing in reverse: shift each boolean back into position and OR the pieces together into two bytes.

A real packet, byte by byte

The repo keeps two captured packets, query_packet.txt and response_packet.txt. The query is 28 bytes:

79 88 01 20 00 01 00 00 00 00 00 00   header: id 0x7988, RD=1, 1 question
06 67 6f 6f 67 6c 65 03 63 6f 6d 00   [6]google[3]com[0]
00 01 00 01                           QTYPE A, QCLASS IN

The response is 44. The sketch below steps through every field. Watch byte 28: it's where things get clever.

A frame from the interactive sketch in the original — watch it run.

Names, labels and compression pointers

Domain names on the wire aren't dotted strings. They're a sequence of labels, each prefixed by its length, ending with a zero-length label:

www.google.com  →  [3] w w w [6] g o o g l e [3] c o m [0]

A length byte can only use 6 of its 8 bits, which is where the famous label limit comes from: $2^{6} - 1 = 63$ characters.

The top two bits are reserved for something much better. If both are set (0b11xxxxxx), the byte isn't a length at all. It's the start of a compression pointer: the remaining 14 bits are an offset elsewhere in the packet where the rest of the name can be found.

$$
\text{offset} = \big((b_0 \mathbin{&} \texttt{0x3F}) \ll 8\big) \mathbin{|} b_1
$$

That's exactly what c0 0c at byte 28 of the response means: offset 0x000C, byte 12, where google.com was already written in the question. Two bytes instead of twelve. In a response with ten records about the same domain, that saving is the difference between fitting in 512 bytes and not.

Here's the flow of read_qname:

Diagram from the original.

And the heart of the code:

fn read_qname(&mut self, outstr: &mut String) -> Result<()> {
    let mut pos = self.pos();   // local cursor, independent of the buffer's
    let mut jumped = false;
    let max_jumps = 5;
    let mut jumps_performed = 0;
    let mut delim = "";

    loop {
        // A crafted packet can contain a pointer loop. Never trust the wire.
        if jumps_performed > max_jumps {
            return Err(format!("Limit of {} jumps exceeded", max_jumps).into());
        }

        let len = self.get(pos)?;

        if (len & 0xC0) == 0xC0 {
            // Move the *shared* cursor past the pointer, but only once
            if !jumped {
                self.seek(pos + 2)?;
            }
            let b2 = self.get(pos + 1)? as u16;
            let offset = (((len as u16) ^ 0xC0) << 8) | b2;
            pos = offset as usize;

            jumped = true;
            jumps_performed += 1;
            continue;
        } else {
            pos += 1;
            if len == 0 {
                break;
            }
            outstr.push_str(delim);
            let str_buffer = self.get_range(pos, len as usize)?;
            outstr.push_str(&String::from_utf8_lossy(str_buffer).to_lowercase());
            delim = ".";
            pos += len as usize;
        }
    }

    if !jumped {
        self.seek(pos)?;
    }
    Ok(())
}

Two details I really like here:

Two cursors. The function walks the name with a local pos, but the buffer's shared cursor has to end up right after the name as it appears in this record. After a jump, those are different places. So the shared cursor is moved exactly once, at the first pointer, and never touched again.
The jump limit. A malicious server can send a pointer that points to itself. Without max_jumps, read_qname would spin forever and one UDP packet would take down the resolver. Five jumps is plenty for any honest packet.

One enum per record type

Answers, authorities and additionals are all resource records with the same envelope: name, type, class, TTL, data length, then type-specific data. Rust's enums model that perfectly:

pub enum DnsRecord {
    UNKNOWN { domain: String, qtype: u16, data_len: u16, ttl: u32 }, // anything else
    A       { domain: String, addr: Ipv4Addr, ttl: u32 },              // 1
    NS      { domain: String, host: String, ttl: u32 },                // 2
    CNAME   { domain: String, host: String, ttl: u32 },                // 5
    MX      { domain: String, priority: u16, host: String, ttl: u32 }, // 15
    AAAA    { domain: String, addr: Ipv6Addr, ttl: u32 },              // 28
}

QueryType has an UNKNOWN(u16) variant too, so a record type the server has never heard of doesn't crash the parser. It reads data_len and skips over the data:

QueryType::UNKNOWN(_) => {
    buffer.step(data_len as usize)?;
    Ok(DnsRecord::UNKNOWN { domain, qtype: qtype_num, data_len, ttl })
}

Reading an A record is four bytes turned into an Ipv4Addr. AAAA is sixteen bytes turned into eight u16 segments. NS, CNAME and MX contain names, so they reuse read_qname, compression pointers and all.

Writing: backpatching the length

Writing has one fun problem. Every record carries an RDLENGTH field before its data, but for a name-valued record you don't know the length until you've written the name. So RustDNS writes a placeholder, writes the data, measures, and goes back to patch it in:

DnsRecord::CNAME { ref domain, ref host, ttl } => {
    buffer.write_qname(domain)?;
    buffer.write_u16(QueryType::CNAME.to_num())?;
    buffer.write_u16(1)?;       // class IN
    buffer.write_u32(ttl)?;

    let pos = buffer.pos();
    buffer.write_u16(0)?;       // placeholder RDLENGTH

    buffer.write_qname(host)?;

    let size = buffer.pos() - (pos + 2);
    buffer.set_u16(pos, size as u16)?;   // backpatch
}

That's what set_u16 was for. It's the same trick assemblers use for forward jumps, and it shows up any time a format puts a length before the thing being measured.

Walking the tree: recursive resolution

Everything so far is a parser. This is the part that makes it a resolver.

lookup() does one round trip: build a packet with one question, send it to one server over UDP, parse whatever comes back:

fn lookup(qname: &str, qtype: QueryType, server: (Ipv4Addr, u16)) -> Result<DnsPacket> {
    let socket = UdpSocket::bind(("0.0.0.0", 43210))?;

    let mut packet = DnsPacket::new();
    packet.header.id = 6666;
    packet.header.questions = 1;
    packet.header.recursion_desired = true;
    packet.questions.push(DnsQuestion::new(qname.to_string(), qtype));

    let mut req_buffer = BytePacketBuffer::new();
    packet.write(&mut req_buffer)?;
    socket.send_to(&req_buffer.buf[0..req_buffer.pos], server)?;

    let mut res_buffer = BytePacketBuffer::new();
    socket.recv_from(&mut res_buffer.buf)?;

    DnsPacket::from_buffer(&mut res_buffer)
}

(Keep an eye on that fixed port 43210 and fixed ID 6666. We'll come back to them.)

recursive_lookup() calls it in a loop, starting at a root server and following referrals downward:

Diagram from the original.

A referral is a response with no answer, but with NS records in the authority section ("ask these servers instead") and, usually, matching A records in the additional section. Those A records are called glue, and they save a round trip: the root doesn't just say "ask l.gtld-servers.net", it also tells you its IP.

Finding the next server with glue is a neat little iterator chain:

pub fn get_resolved_ns(&self, qname: &str) -> Option<Ipv4Addr> {
    self.get_ns(qname)                      // (domain, host) pairs from NS records
        .flat_map(|(_, host)| {
            self.resources.iter().filter_map(move |record| match record {
                DnsRecord::A { domain, addr, .. } if domain == host => Some(addr),
                _ => None,
            })
        })
        .map(|addr| *addr)
        .next()                             // first NS that has glue wins
}

When there's no glue (the nameserver lives in a different zone, like GitHub's ns-421.awsdns-52.com), the resolver has to stop, resolve the nameserver's name from scratch, then continue. That's literally recursion: recursive_lookup calls itself.

let new_ns_name = match response.get_unresolved_ns(qname) {
    Some(x) => x,
    None => return Ok(response),
};

// Down the rabbit hole: a whole new lookup in the middle of this one.
let recursive_response = recursive_lookup(&new_ns_name, QueryType::A)?;

if let Some(new_ns) = recursive_response.get_random_a() {
    ns = new_ns;
} else {
    return Ok(response);
}

Here's the google.com run from earlier as a sequence, with the real servers from the log:

Diagram from the original.

And here it is moving. The upstream legs are slowed down so you can follow them. Click the canvas to switch to what a cache would do (more on that later; RustDNS doesn't have one yet):

A frame from the interactive sketch in the original — it does not render here.

Serving dig on port 2053

The last layer turns the resolver into a server. main() is a single loop:

fn main() -> Result<()> {
    let socket = UdpSocket::bind(("0.0.0.0", 2053))?;
    loop {
        match handle_query(&socket) {
            Ok(_) => {}
            Err(e) => eprintln!("An error occurred: {}", e),
        }
    }
}

An error in one query is logged and the loop moves on, so one bad packet never kills the server. handle_query receives a packet, resolves it, and builds a response:

Diagram from the original.

let mut packet = DnsPacket::new();
packet.header.id = request.header.id;        // echo the client's ID
packet.header.recursion_desired = true;
packet.header.recursion_available = true;
packet.header.response = true;

if let Some(question) = request.questions.pop() {
    if let Ok(result) = recursive_lookup(&question.name, question.qtype) {
        packet.questions.push(question.clone());
        packet.header.rescode = result.header.rescode;
        packet.answers.extend(result.answers);       // (the repo uses for-loops with logging)
        packet.authorities.extend(result.authorities);
        packet.resources.extend(result.resources);
    } else {
        packet.header.rescode = ResultCode::SERVFAIL;
    }
} else {
    packet.header.rescode = ResultCode::FORMERR;
}

The response codes are the polite part of the protocol. A failed upstream lookup becomes SERVFAIL ("I tried, it broke"), and a packet with no question becomes FORMERR ("that's not a valid query"). The client always gets something back.

At least, that was the theory.

Breaking it on purpose

I wrote RustDNS in September 2024. To write this post, I built it again and threw real queries at it. Most worked. Two did not, and both are great lessons in why protocols look the way they do.

Bug 1: the MX query that never came back

Received query: DnsQuestion { name: "gmail.com", qtype: MX }
attempting lookup of MX gmail.com with ns 198.41.0.4
attempting lookup of MX gmail.com with ns 192.41.162.30
attempting lookup of MX gmail.com with ns 216.239.34.10
Answer: MX { domain: "gmail.com", priority: 5, host: "gmail-smtp-in.l.google.com", ttl: 3600 }
...   (5 MX answers, then 5 A and 5 AAAA additional records)
An error occurred: End of the buffer

The resolution succeeded. Google's server sent five MX records plus glue for every mail host, and that response fit comfortably in 512 bytes because Google compresses names with pointers.

RustDNS doesn't compress when it writes. write_qname spells every name out in full, so the same response grows:

Part	Bytes, uncompressed
Header + question	27
5 MX answers	275
5 A additionals	230
5 AAAA additionals	290
Total	822

The writer runs out of room partway through the A records, write() returns Err("End of the buffer"), handle_query bails out with ?, and the error is logged. Nothing is sent. The client just waits until it times out. My Python client gave up after 20 seconds.

The fix is a ladder of increasingly blunt tools, and real resolvers use all of them:

Compress names on write. Keep a map of name → offset while writing and emit a pointer the second time a name appears. That alone would shrink this response well under 512 bytes.
Drop the additional section. Glue records are optional hints. Header, question and answers here are only 302 bytes.
Set the TC bit. If even that doesn't fit, send what you can with truncated_message = true, which tells the client to retry over TCP. (RustDNS would then also need a TCP listener.)
EDNS(0), from RFC 6891, lets client and server agree on UDP payloads larger than 512 bytes.

A sketch of step 2, which is a few lines:

// Sketch, not in the repo yet
let mut res_buffer = BytePacketBuffer::new();
if packet.write(&mut res_buffer).is_err() {
    packet.resources.clear();                  // additionals are optional
    res_buffer = BytePacketBuffer::new();
    if packet.write(&mut res_buffer).is_err() {
        packet.answers.clear();
        packet.authorities.clear();
        packet.header.truncated_message = true; // "retry over TCP"
        res_buffer = BytePacketBuffer::new();
        packet.write(&mut res_buffer)?;
    }
}

Bug 2: an NXDOMAIN that lies about itself

Asking for a name that doesn't exist looked fine in the logs:

Received query: DnsQuestion { name: "doesnotexist-xyz123.com", qtype: A }
attempting lookup of A doesnotexist-xyz123.com with ns 198.41.0.4
attempting lookup of A doesnotexist-xyz123.com with ns 192.41.162.30
Authority: UNKNOWN { domain: "com", qtype: 6, data_len: 61, ttl: 900 }
Skipping record: UNKNOWN { domain: "com", qtype: 6, data_len: 61, ttl: 900 }

Type 6 is SOA, the record a server attaches to an NXDOMAIN so resolvers know how long to cache the "no". RustDNS doesn't model SOA, so it parses it as UNKNOWN, and when writing, UNKNOWN writes nothing at all. But DnsPacket::write sets the header counts from the vectors before writing:

self.header.authoritative_entries = self.authorities.len() as u16; // 1

So the response says "one authority record follows", and then the packet ends:

12 34 81 83 00 01 00 00 00 01 00 00  13 64 6f 65 73 ...
         ^ RCODE=3         ^ NSCOUNT = 1, but zero bytes of records follow

A lenient client shrugs and reads the NXDOMAIN rcode. A strict one rejects the whole packet as malformed. The quick fix is one line: packet.authorities.retain(|r| !matches!(r, DnsRecord::UNKNOWN { .. })) before writing. The proper fix is adding an SOA variant to DnsRecord. Either way, a header count is a promise, and a writer must never count something it doesn't write.

Smaller things I found reading the code again

Label length check. write_qname rejects labels longer than 0x34, which is 52, but the error message (and the spec) say 63. It should be 0x3F.
Off-by-one in get_range. It errors when start + len >= 512, so a range ending exactly at byte 512 is rejected. That should be >.
get_random_a isn't random. It returns the first A record. Harmless, but the name over-promises.
Zone matching with ends_with. get_ns keeps NS records where qname.ends_with(domain), so notgoogle.com "ends with" google.com. Comparing on a label boundary (qname == domain or qname.ends_with(&format!(".{}", domain))) is the correct check.

The serious one: spoofing

Remember lookup()? Every upstream query goes out from port 43210 with ID 6666, and the reply's ID is never checked. An attacker who can send UDP packets to the resolver only has to guess... nothing. They can race a forged answer for any name and it will be believed.

This is the class of attack Dan Kaminsky made famous in 2008, and the industry's response was to make forgeries expensive to guess: a random 16-bit ID and a random source port, roughly $2^{16} \times 2^{16} \approx 4.3 \times 1 0^{9}$ combinations instead of one. It's a small change:

// Sketch, not in the repo yet
use std::collections::hash_map::RandomState;
use std::hash::{BuildHasher, Hasher};
use std::time::Duration;

fn random_u16() -> u16 {
    RandomState::new().build_hasher().finish() as u16 // fine for a toy; use getrandom for real
}

let socket = UdpSocket::bind(("0.0.0.0", 0))?;           // OS picks a random ephemeral port
socket.set_read_timeout(Some(Duration::from_secs(2)))?;  // a dead server can't hang us forever
let id = random_u16();
// ... send, receive ...
if response.header.id != id {
    return Err("response ID mismatch".into());
}

The read timeout fixes a quieter problem too: today, if an upstream server never answers, recv_from blocks forever and the whole server freezes with it.

How fast is it?

Every query I sent was a cold lookup, because RustDNS doesn't cache anything. Each one walked root → TLD → authoritative, and took between 533 and 568 ms end to end on my connection.

That's almost entirely network time. Cold latency is roughly the sum of the round trips:

$$
T_{\text{cold}} \approx \sum_{i=1}^{h} \mathrm{RTT}_i \qquad (h = 3 \text{ for google.com})
$$

Parsing a 44-byte packet takes microseconds; waiting on three servers in a row takes hundreds of milliseconds. Which is why every real resolver caches. With a hit rate $p$ :

$$
\mathbb{E}[T] = p \cdot T_{\text{hit}} + (1 - p) \cdot T_{\text{miss}}
$$

At a modest 90% hit rate, with a hit costing about 1 ms and a miss 550 ms, the average drops from 550 ms to about 56 ms. The TTL on each record (300 seconds for Google's A records, 3600 for the gmail MX records) is the server telling you exactly how long you're allowed to keep it.

There's a second, sneakier cost. The server handles one query at a time. While it spends half a second walking the tree for one client, every other client waits in the socket's queue. And because lookup() binds a fixed port, you couldn't simply spawn a thread per request: the second thread would fail with "address in use". The spoofing fix above (port 0) happens to unblock concurrency too.

What I learned

Binary protocols are honest. There is no "kind of parsed". Either the 12 bytes are a header or they aren't, and Rust's Result plus ? on every read made each failure path explicit rather than a crash waiting to happen.
Every limit has a story. 512 bytes, 63-character labels, 14-bit pointers, 16-bit IDs. Each one is a design decision from 1987 that the internet has spent decades working around with compression, TCP fallback and EDNS.
Parsing and writing are not symmetric. RustDNS reads compression pointers perfectly and never writes one. That asymmetry is invisible on small answers and fatal on large ones.
Header counts are promises. Counting a record you then skip produces a packet that's wrong in a way only a strict parser notices.
Never trust the wire. The jump limit in read_qname is the line I'm proudest of, and the fixed query ID is the one I'd fix first. Same lesson, both directions.
DNS is a cache with a protocol attached. Resolution itself is a handful of round trips. Everything that makes it fast in practice is caching and TTLs.

What's next

TTL cache. A HashMap<(String, QueryType), (Vec<DnsRecord>, Instant)> behind a Mutex, respecting each record's TTL, including negative caching from the SOA.
Concurrency. A thread per request with socket.try_clone(), or a move to tokio, once upstream sockets use ephemeral ports.
Spoofing defences. Random IDs and source ports, ID verification and read timeouts, as sketched above.
Name compression on write, plus graceful truncation with the TC bit.
More record types: SOA, TXT, SRV and PTR.
TCP and EDNS(0) for responses bigger than 512 bytes.
A config.toml for the listen address, root hints and an optional upstream forwarder.
Tests built on the captured packets in the repo, so every fix above comes with a regression test.

Try it

git clone https://github.com/ravikisha/rustdns && cd rustdns
cargo run --release

# in another terminal
dig @127.0.0.1 -p 2053 google.com
dig @127.0.0.1 -p 2053 www.github.com
dig @127.0.0.1 -p 2053 gmail.com MX   # spoiler: see "Breaking it on purpose"

It's a single file with no dependencies, so it's a nice codebase to read in one sitting. If you've never looked inside DNS, I'd recommend opening main.rs next to RFC 1035 and a packet capture; it all clicks surprisingly fast.

If you liked this kind of build-it-to-understand-it post, I've done the same for link checkers in Rust and for calling Rust from Node.js.

⭐ Star it on GitHub, and if you'd like to pick up anything from the "What's next" list, open an issue or a PR. The NXDOMAIN fix is a great first contribution.

Happy resolving! 🦀

Photo credits: cover and rack photos by Derrick Coetzee, CC0, via Wikimedia Commons. Bell System switchboard, public domain, U.S. National Archives. 1928 Rikstelefonkatalogen, public domain, Televerket Sverige.

Relaxnative: Import C, C++, Rust, Zig and Go Straight into Node.js

Ravi Kishan — Mon, 05 Oct 2026 08:01:26 +0000

TL;DR: Relaxnative is a Node.js library that lets you write a function in C, C++, Rust, Zig or Go, point loadNative() at the file, and call it from JavaScript like any other function. No node-gyp, no binding.gyp, no hand-written N-API glue. It compiles on first import, caches by content hash, can ship prebuilt so production needs no compiler, and lets you choose how much a native crash is allowed to hurt.
npm i relaxnative
🔗 GitHub · 📦 npm · 🐛 Issues

Why I built this
Hello, native
Five languages, one call
What loadNative() actually does
Reading signatures: tree-sitter and friends
The types contract
A cache keyed by everything
Ahead-of-time builds: no compiler in production
Three isolation modes
Annotations: @sync, @async, @cost
Benchmarks: where native wins (and where it loses)
RelaxRegistry and supply-chain trust
Developer experience
What I learned
What's next

Why I built this

JavaScript is fast, often surprisingly fast. But every Node developer eventually hits a wall where it isn't fast enough:

64-bit integer math. JS numbers are doubles, so real u64 work means BigInt, and BigInt is slow.
Raw byte crunching, like image pixels, checksums and histograms, where you want tight loops over memory with no bounds checks.
Code that already exists in C or Rust that you'd rather reuse than rewrite.

The traditional answer is a native addon: node-gyp, a binding.gyp, N-API boilerplate, a C++ wrapper per function, and a build that breaks on every other Windows machine. It works, but it's a lot of ceremony for "I want to call add(a, b) written in C".

I wanted something closer to Python's ctypes or Bun's bun:ffi, but for plain Node, for several languages, and with real answers for safety. What happens when native code segfaults? What happens when you install someone else's native code? That's Relaxnative.

Hello, native

Create native/add.c:

// @sync
int add(int a, int b) {
  return a + b;
}

Call it from JavaScript:

import { loadNative } from 'relaxnative';

const mod = await loadNative('native/add.c', { isolation: 'worker' });
console.log(mod.add(1, 2)); // 3

That's the whole integration. The first loadNative() finds a compiler, builds a shared library, reads the function signatures out of your source and binds them. Every later run hits the cache.

Not sure which toolchains you have? Ask:

npx relaxnative doctor

✓ C compiler detected (clang 22.1.8)
✓ C++ compiler detected (clang 22.1.8)
✓ Rust compiler detected (rustc 1.97.1)
✗ Zig compiler missing (install zig)
✓ Go toolchain detected (go-wsl: go1.22.2 linux/amd64)
✓ Worker threads supported
✓ Cache directory OK
✓ ESM loader supported (Node >= 18)

Five languages, one call

Each language compiles to a C-ABI shared library (.dll / .so / .dylib), so from JavaScript they all look the same:

Language	Extension	How you export	Compiler
C	`.c`	plain top-level functions	clang / gcc / MSVC `cl` / `zig cc`
C++	`.cpp` `.cc` `.cxx`	`extern "C"` functions	clang++ / g++ / `cl` / `zig c++`
Rust	`.rs`	`#[no_mangle] pub extern "C" fn`	`rustc --crate-type cdylib`
Zig	`.zig`	`export fn`	`zig build-lib -dynamic`
Go	`.go`	`//export Name` + `import "C"`	`go build -buildmode=c-shared`

// add.rs
#[no_mangle]
pub extern "C" fn add(a: i32, b: i32) -> i32 { a + b }

// add.zig
export fn add(a: i32, b: i32) i32 { return a + b; }

// add.go
package main
import "C"
//export add
func add(a, b C.int) C.int { return a + b }
func main() {}

const mod = await loadNative('native/add.zig', { isolation: 'in-process' });
console.log(mod.add(20, 22)); // 42

One Zig install is a cheat code here: zig cc and zig c++ are clang-based, so a single download covers C, C++ and Zig.

Go on Windows was the fun one. To build a real Windows DLL, Relaxnative cross-compiles inside WSL with GOOS=windows CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc go build -buildmode=c-shared, so you only need go and mingw-w64 inside your distro.

Multi-file builds work too. Extra C/C++ sources get linked into the same library, Rust files are mod-declared, Zig files are @imported, and Go files form one main package:

const mod = await loadNative('native/main.c', {
  isolation: 'in-process',
  build: {
    sources: ['native/helper.c'],
    includePaths: ['native/include'],
    libraries: ['m'],
    flags: ['-O3'],
  },
});

What `loadNative()` actually does

The whole library is built around one pipeline in src/loader.ts:

Prebuilt? If .relaxnative/prebuilt/ has an artifact for this platform and this exact source content, use it and skip compiling entirely.
Detect the toolchain for the file's language (clang, gcc, cl, zig, rustc, go).
Hash the compile inputs. On a cache hit, reuse the library.
Compile to a shared library on a miss. C/C++ get -O2 by default, because building at -O0 makes native code lose badly to V8's JIT and that's an embarrassing benchmark.
Parse the signatures from your source to learn names, parameter types and return types.
Bind them with koffi, a fast FFI library for Node.
Wrap each function according to the isolation mode you picked.

The result is a plain object of JavaScript functions.

Reading signatures: tree-sitter and friends

To bind a function, Relaxnative has to know its signature without you writing it twice. So it reads your source:

C, C++ and Rust are parsed with tree-sitter grammars, giving a real syntax tree instead of regex guesses.
Zig and Go use small lexical scanners that look for export fn and //export and map types like i32, [*]u8 or C.int to the shared type model.

Real C is messier than it looks, and the parser has the scars to prove it. My favourite: for a pointer-returning function like char *greet(int), tree-sitter nests the function declarator inside a pointer_declarator and hangs the * there, not on the return type. The first version read the name as greet(int), found no parameters, decided the return type was unknown, and silently dropped the function. The fix unwraps every pointer_declarator layer and folds the stars back into the return type.

Other details it handles:

foo(void) means "no parameters", so the lone void is dropped.
Variadic functions (printf-style) are detected and rejected instead of being called with a garbage stack.
Pointer stars can live in the declarator (uint8_t *buf), so type and declarator text are combined with a space. Otherwise unsigned long long x becomes unsigned long longx.

And there's a rule: if a type isn't recognized, fail fast. A wrong FFI signature doesn't throw a nice error. It corrupts memory.

The types contract

Concept	C / C++	Rust	Zig	Go (cgo)
32-bit int	`int` / `int32_t`	`i32`	`i32`	`C.int`
64-bit int	`int64_t`	`i64`	`i64`	`int64`
float / double	`float` / `double`	`f32` / `f64`	`f32` / `f64`	`float32` / `float64`
bool	`bool`	`bool`	`bool`	`bool`
byte buffer	`uint8_t*`	`*mut u8`	`[*]u8`	`*byte`
C string	`const char*`	`*const i8`	`[*c]const u8`	`*C.char`

On the JavaScript side:

Scalars become number. 64-bit integers can come back as bigint and accept either.
Pointers accept TypedArrays: pass a Uint8Array for uint8_t* or a Uint32Array for uint32_t*. Native code writes straight into your array.
const char* parameters and returns are plain JS strings.
For manual memory there's native.alloc(size), which returns a NativeBuffer with an .address.

// @async
void histogram_u8(const uint8_t* data, int n, uint32_t* out256) {
  for (int i = 0; i < 256; i++) out256[i] = 0;
  for (int i = 0; i < n; i++) out256[data[i]]++;
}

const { histogram_u8 } = await loadNative('native/histogram.c', { isolation: 'worker' });
const data = new Uint8Array(1024 * 1024);
const out = new Uint32Array(256);
await histogram_u8(data, data.length, out); // out is filled in place

Tip: prefer fixed-width types (uint32_t* over unsigned*). They make the parser's job unambiguous, and they're better C anyway.

A cache keyed by everything

Compiling on every import would be unbearable, so builds are cached under ~/.relaxnative/cache. The key is a SHA-256 over everything that changes the output binary:

// src/cache/hash.ts (simplified)
for (const p of [sourcePath, ...sources]) hash.update(readFileSync(p)); // CONTENTS, not paths
hash.update(compiler.path + compiler.version);
hash.update(flags.join(' '));
hash.update(includePaths.join(' '));
hash.update(libraryPaths.join(' '));
hash.update(libraries.join(' '));
hash.update(platform); // e.g. win32-x64

Two bugs taught me this list. Originally only the entry file was hashed, so editing a helper file in a multi-file build gave a false cache hit: you changed code and nothing happened. Now every source's contents are hashed. And a failed compile used to leave a half-populated cache directory behind. Now a cache entry only counts once its meta.json exists, and failed builds clean up after themselves.

npx relaxnative cache status
npx relaxnative cache clean

Ahead-of-time builds: no compiler in production

Compile-on-import is lovely in development and a liability in a slim Docker image. So there's an AOT mode:

npx relaxnative build native/add.c native/kernel.zig native/svc.go

Or declare targets once in relaxnative.build.json:

{
  "targets": [
    { "source": "native/add.c" },
    {
      "source": "native/mathkernel/main.c",
      "sources": ["native/mathkernel/helper.c"],
      "libraries": ["m"],
      "flags": ["-O3"]
    }
  ]
}

This writes the compiled libraries plus the parsed bindings to .relaxnative/prebuilt/. Ship that folder, and at runtime loadNative() uses a prebuilt artifact when it matches the current platform and the source's current content hash. No compiler, no parser work.

If you edit the source after building, the hash no longer matches and it quietly falls back to compiling, which is exactly what you want in development. RELAXNATIVE_NO_PREBUILT=1 turns the fast path off.

Three isolation modes

Here's the uncomfortable truth about native code: a segfault doesn't throw, it kills the process. No try/catch saves you. So Relaxnative makes the blast radius a per-call choice:

await loadNative('native/kernel.c', { isolation: 'in-process' }); // fastest
await loadNative('native/kernel.c', { isolation: 'worker' });     // default
await loadNative('native/kernel.c', { isolation: 'process' });    // safest

in-process calls the function directly on the JS thread. It has the lowest overhead and no safety net. Use it for trusted, hot code.

worker (the default) sends async work to a worker-thread pool so heavy calls don't block the event loop. To keep tiny calls cheap, sync functions still run in-process. That means worker mode is not crash-safe for sync functions, and the code comments say so plainly.

process forks a helper process and talks to it over IPC. It's the heavyweight option, and it buys you a lot:

Crash containment. If the native code segfaults, the helper dies, your app gets a ProcessIsolationError with code ISOLATED_PROCESS_CRASH (and the JS callsite that made the call), and the helper restarts.
Per-call timeouts. An infinite loop gets the helper killed instead of hanging forever.
A best-effort memory cap. The helper watches its own RSS and exits if it goes over.
Permission guards. Inside the helper, imports of fs, net/http/dns/tls, and child_process are denied unless granted. worker_threads, vm, v8 and inspector are always blocked because each one is an isolation escape hatch. Blocking is by module family, so node:fs/promises can't slip past a check for fs.

All calls in process mode are async, since there's an IPC boundary in the way.

I'm careful about wording here, and so is the threat model: this is defense in depth, not a sandbox. Native code can make raw syscalls that no Node-level guard can see. Kernel-level sandboxing (seccomp, AppContainer, sandbox-exec) is explicitly a non-goal for now.

Annotations: `@sync`, `@async`, `@cost`

How does the wrapper know whether a function should return a value or a Promise? You tell it, in a comment up to 3 lines above the function:

// @async
// @cost high
int heavy(int n) {
  long x = 0;
  for (int i = 0; i < n * 10000000; i++) x += i;
  return (int)x;
}

Annotation	Effect
`@sync`	Returns a plain value. In `worker` mode it may run on the main thread for speed.
`@async`	Returns a `Promise` and always goes through the worker in `worker` mode.
`@cost high`	Treated like `@async`, so heavy work stays off the event loop.

You can also override per call: loadNative(path, { config: { functionMode: { add: 'sync' }, defaultMode: 'async' } }).

Benchmarks: where native wins (and where it loses)

I didn't want to write a "native is 1000× faster!!" post, because it isn't, at least not always. Every FFI call has a fixed cost of a few microseconds. Native only wins when each call does enough work to pay that back.

The numbers above come from the in-repo suites (benchmark.report.test.ts and benchmark.realworld.test.ts), using in-process isolation. They tell a clear story:

64-bit integers: 53×. JS has to use BigInt, while native uses raw u64. I re-ran a xorshift kernel in Rust on a different Windows machine while writing this post and got ~74× (2000 × 4000 iterations: 6.7 s in JS, 91 ms native), with results matching JS bit for bit.
Raw buffers: 14× for summing 1 MiB, and 6.7× for RGBA→grayscale on a 2.1 MP image.
Float-heavy loops: about 1.1–2×. V8's JIT is genuinely excellent at number math, so Mandelbrot and dot products barely move.
A trivial a + b: 0.01×, roughly 80× slower. The FFI crossing costs far more than the addition, which V8 would simply inline.

The same u64 kernel across languages is a nice sanity check that it's the workload, not the language, that matters:

Language	Calls/s	vs JS
JS (V8, BigInt)	1,945	1.0×
Rust	28,503	14.7×
Go	40,560	20.9×
C (`zig cc`)	42,242	21.7×
Zig	45,304	23.3×

The rule of thumb: cross the boundary rarely, and do a lot of work each time. Batch your data into TypedArrays and make one big call, not a million small ones.

You can benchmark your own kernels against a plain-JS baseline:

npx relaxnative bench examples/matmul.c matmul_f32 --traditional --iterations 5 --warmup 1

RelaxRegistry and supply-chain trust

Once loading native code is this easy, the next question is scary: what about native code from someone else? An npm package can at least be sandboxed by your judgement. A native package can do anything your user account can.

So Relaxnative ships a small package system, RelaxRegistry, built with trust in mind:

npx relaxnative add file:examples/registry/fast-matrix
npx relaxnative list
npx relaxnative remove fast-matrix

Each package has a relax.json declaring its exports, the permissions it wants, and a trust level:

local: your own code. No prompts.
community: third-party code. You get a warning and must consent. Elevated permissions (fs, network, spawn) are refused, and isolation is forced to process.
verified: elevated trust, but only if a real cryptographic signature checks out. Otherwise the package is demoted to community.

Before any of that, a static scan flags risky APIs such as system, popen, exec*, fork, CreateProcessW and raw sockets. It strips comments, splices backslash line-continuations and blanks out string literals first, so sys\<newline>tem or "sy" "stem" can't dodge it. It's still only a heuristic, and the code says so.

Signing, done properly

My first design had a digest field and treated a matching digest as "verified". That's wrong, because anyone can recompute a hash. Integrity isn't authenticity. The final design has two separate layers:

{
  "trust": "verified",
  "registrySignature": {
    "alg": "sha256",
    "digest": "<sha256 over canonical manifest + per-source hashes>",
    "sources": { "add.c": "<sha256>" },
    "keyId": "relaxnative-registry-2026",
    "signature": "<base64 Ed25519 over the digest>"
  }
}

Integrity: the digest covers the manifest and every source file's content. It's computed over canonical JSON (keys sorted recursively, no whitespace), so reformatting the file can't change it. Any tampering fails the install.
Authenticity: an Ed25519 signature over that digest, verified against a pinned public key. Only this grants verified. Keys are bundled or provided via RELAXNATIVE_TRUSTED_KEYS, and signPackage() produces signatures.

Consent is content-pinned too. Your "yes" is stored with the package's content digest in native/registry/.trust.json, so if someone republishes the same name@version with different bytes, you're asked again. And the low-level raw installer is deliberately not exported. Every install goes through the trust-enforcing path, so there's no shortcut that skips the gate.

Developer experience

A few things that make day-to-day use pleasant:

Tracing. When a crash happens behind a worker or process boundary, the real error is easy to lose. RELAXNATIVE_TRACE=1 prints lifecycle events (loadNative.begin, build.done, dispatch, isolation.process.call…), and RELAXNATIVE_TRACE_LEVEL=debug also prints every parsed signature.

Hot reload. With RELAXNATIVE_DEV=1, loadNative() returns a stable proxy that watches the source file, rebuilds on save and swaps the implementation in place. It fingerprints the ABI (names, argument types, return types), so it knows when a change is more than a body edit.

An ESM loader. Run Node with --loader relaxnative/loader and you can import native files directly:

// node --loader relaxnative/loader app.js
import math from './native/add.c';

It currently handles C, C++ and Rust sources, plus relaxnative/<package> registry specifiers, with package names validated so relaxnative/../../etc/passwd goes nowhere.

A native test harness. Write tests in C:

int test_add() { return add(2, 2) == 4 ? 0 : 1; }      // 0 = pass
const char* test_msg() { return NULL; }                // NULL/"" = pass

npx relaxnative test native/examples --isolation process

Running tests in process isolation means a segfaulting test fails that test instead of taking down the runner.

Express in five lines:

import express from 'express';
import { loadNative } from 'relaxnative';

const app = express();
const native = await loadNative('native/loop.c', { isolation: 'worker' });
app.get('/sum', (req, res) => res.json({ v: native.loop_sum(Number(req.query.n ?? 1e6)) }));
app.listen(3000);

What I learned

FFI cost is the whole game. Native isn't faster per se. It's faster per unit of work, and only once that work dwarfs the few-microsecond crossing. The 0.01× add benchmark taught me more than the 53× one.
V8 is a formidable opponent. For plain float loops the JIT is within a whisker of -O2 C. Real wins come where JS is structurally weak: 64-bit ints and raw memory.
Parsing C is humbling. Pointer declarators, (void), variadics and multi-word types: every edge case is a silent-corruption bug waiting to happen. "Fail fast on unknown types" became a core principle.
Hashes aren't signatures. Separating integrity (the digest) from authenticity (Ed25519 with a pinned key) was the most important security fix in the project.
Be honest about safety. It's tempting to call process isolation a "sandbox". It isn't, and the docs and threat model say exactly what is and isn't protected.

What's next

Fix clang on Windows MSVC targets. It currently rejects -fPIC, which is why my demo above used Rust. zig cc or cl work today.
Cache toolchain detection so that warm loads skip probing compilers (and WSL) on every call.
Bring Zig and Go to the ESM loader.
Richer types: structs and callbacks.
An optional hardened runtime: seccomp-bpf on Linux, AppContainer on Windows, sandbox-exec on macOS.

Try it

mkdir my-native-app && cd my-native-app
npm init -y && npm pkg set type=module
npm i relaxnative
npx relaxnative doctor

⭐ Star it on GitHub, install it from npm, and if you find a signature it can't parse or a kernel where native loses, open an issue. Those are my favourite bug reports.

Happy hacking! ⚡

Relaxicons: Turn Any Iconify Icon into a Native Component for 8 Frameworks

Ravi Kishan — Mon, 05 Oct 2026 07:24:51 +0000

TL;DR — Relaxicons is a Node.js CLI that pulls any icon from the Iconify catalogue (200+ open-source icon sets) and writes it into your project as a real component for React, Next.js (RSC), Vue, Angular, Svelte, Solid, Laravel Blade or Web Components. One command, one file, no runtime icon library.
npm install -g relaxicons
relaxicons init
relaxicons add lucide:home
🔗 GitHub · 📦 npm · 📚 Docs · 🔍 Icon Explorer

The problem: icons are weirdly annoying
The idea: shadcn, but for icons
A 60-second tour
What happens when you run relaxicons add
The SVG transform pipeline (and the outline-icon trap)
One prop contract, eight frameworks
Caching that respects the network
The small details that make a CLI pleasant
Icons in CI
The docs site
Testing
What I learned
What's next

The problem: icons are weirdly annoying

Every frontend project hits the same wall sooner or later. You need one home icon. Your options are usually:

Install a whole icon package (react-icons, @mdi/js, lucide-react…). Great until you want an icon from a different set, and now you have two dependencies, two APIs and two styling conventions.
Use a runtime icon loader that fetches SVGs from a CDN in the browser. Flexible, but now your icons depend on a network request at render time.
Copy-paste the SVG from a website. Fast, but you end up with hard-coded width="24", a random fill="#000", kebab-case attributes that React complains about, and zero consistency between files.

None of these felt right to me. I wanted the icon in my repo, as code I own, written in the idiom of whatever framework I'm using — and I wanted it from any icon set without thinking about it.

That's why I built Relaxicons.

The idea: shadcn, but for icons

The mental model is close to how shadcn/ui treats components: don't install a library, generate the source into your project.

Iconify already did the heavy lifting of collecting icon sets — Lucide, Material Design Icons, Tabler, Phosphor, Font Awesome, Heroicons, and hundreds more — behind a single, consistent API. Every icon has an ID like collection:name:

lucide:home
mdi:github
tabler:brand-react
ph:rocket-launch

Relaxicons sits on top of that API. You give it an ID, and it gives you back a component file that:

has no width/height baked in (it scales with a size prop, default 1em),
uses currentColor so it inherits your text color,
exposes the same props in every framework (size, color, strokeWidth, className/class),
is formatted with Prettier, and
is automatically exported from an index.ts barrel file.

No runtime. No icon package. Just a file.

A 60-second tour

Install the CLI globally (Node 18+):

npm install -g relaxicons
relaxicons --version   # 1.1.2

Initialize inside your project. Relaxicons sniffs your project to figure out what you're using:

relaxicons init
# ✔ Detected: Next.js
# ? Confirm framework › Next.js
# ? Where do you want to save icons? › components/ui/icons
# ? Do you use TypeScript? › yes
# ✔ Created relaxicons.config.json

That writes a small config:

{
  "framework": "next",
  "iconPath": "components/ui/icons",
  "typescript": true,
  "schemaVersion": 2,
  "generatedAt": "2026-10-05T00:00:00.000Z"
}

Now add icons — one, several, or a whole file of them:

relaxicons add lucide:home
relaxicons add lucide:home,star,bell          # shared prefix shorthand
relaxicons add mdi:github,tabler:brand-react   # mix collections
relaxicons add --from icons.txt                # batch from a file

And use them like any other component:

import { HomeIcon, StarIcon } from '@/components/ui/icons';

export default function Nav() {
  return (
    <nav className="text-slate-600">
      <HomeIcon />                         {/* inherits text color, 1em */}
      <StarIcon size={24} color="gold" />  {/* explicit size + color */}
    </nav>
  );
}

Need to find an icon first? Explore from the terminal:

relaxicons collections --filter luc
relaxicons icons lucide --filter clock --limit 10
relaxicons search arrow --collection lucide
relaxicons stats -c lucide

…or use the visual Icon Explorer on the docs site and copy the command straight from there.

What happens when you run `relaxicons add`

Under the hood, add is a small, linear pipeline. Here's the whole journey of relaxicons add lucide:home:

  lucide:home
      │
      ▼
┌──────────────┐   relaxicons.config.json → framework, iconPath, typescript
│  getConfig   │   (--framework flag can override per call)
└──────┬───────┘
       ▼
┌──────────────┐   GET https://api.iconify.design/lucide/home.svg
│  fetchIcon   │   404 → fuzzy "Did you mean…?" suggestions
└──────┬───────┘
       ▼
┌──────────────┐   optional, only if svgo is installed
│  SVGO        │
└──────┬───────┘
       ▼
┌──────────────┐   strip width/height, currentColor, drop data-* attrs
│ transformSvg │   → { attrs, children }
└──────┬───────┘
       ▼
┌──────────────┐   custom template (.hbs/.ejs/.js) if present,
│  template    │   otherwise built-in react/vue/angular/svelte/…
└──────┬───────┘
       ▼
┌──────────────┐   parser picked from file extension
│  Prettier    │
└──────┬───────┘
       ▼
┌──────────────┐   HomeIcon.tsx + sorted `export * from './HomeIcon'`
│ write+barrel │
└──────────────┘

A few parts of that are worth zooming into.

Parsing the ID

fetchIcon accepts both lucide:home and lucide/home, and rejects anything that isn't exactly two non-empty parts with a helpful message. It then validates that the response actually is an SVG (optionally preceded by an XML prolog) before trusting it — if Iconify ever returns an HTML error page, you get Unexpected response: not an SVG instead of a broken component.

Safe names

Icon names on Iconify are wild. Some start with digits (500px), some are JavaScript reserved words (default, class, function), some are pure symbols. A generated component must be a valid identifier, so names go through two passes:

toPascalCase('arrow-right')  // ArrowRight
safePascal('Default')        // fine — PascalCase isn't reserved
safePascal('500px')          // Icon500px  (leading digit)
safePascal('')               // Icon       (nothing left after cleaning)
safeKebab('ÅÄÖ')             // icon

The same sanitized names are reused by relaxicons remove, so removing an icon always finds the file add created.

The SVG transform pipeline (and the outline-icon trap)

This is the most interesting file in the project: src/utils/transformSvg.js. It loads the SVG with cheerio in XML mode and does four things:

Removes width and height from the root, keeping viewBox, so the component can scale freely.
Applies currentColor so icons inherit the surrounding text color.
Strips noise like data-name / data-style attributes left behind by design tools.
Returns a neutral representation — { attrs, children } — that every framework template consumes.

Step 2 sounds trivial ("just set fill="currentColor" everywhere"), and that's exactly the trap I fell into first.

Icon sets come in two flavours:

Style	Examples	How it's drawn
Filled	MDI, Material Symbols, Font Awesome	Shapes painted with `fill`
Outline	Lucide, Feather, Tabler	`fill="none"` + `stroke`, lines only

If you blindly add fill="currentColor" to every <path> in an outline icon, the strokes get filled in and your crisp line icon turns into a solid blob. So the transform first asks: is this an outline icon?

const rootFillNone = $svg.attr("fill") === "none";
const rootHasStroke = !!$svg.attr("stroke");
const isOutline = rootFillNone || rootHasStroke;

…and only then decides, per element:

element has a stroke-width but no stroke → give it stroke="currentColor";
element already has its own fill (even fill="none") → never touch it;
outline icon, or the element itself is stroke-based → leave fill unset so it inherits none;
otherwise, for real shapes (path, circle, rect, polygon, polyline, ellipse) → fill="currentColor".

The trap had a second layer, and I only found it while writing this post. The Iconify API doesn't put Lucide's fill="none" on the root at all. It wraps every path in a group:

<svg viewBox="0 0 24 24">
  <g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <path d="M15 21v-8a1 1 0 0 0-1-1h-4…"/>
    <path d="M3 10a2 2 0 0 1 .709-1.528l7-6…"/>
  </g>
</svg>

A root-only check sees no outline, so relaxicons add lucide:home produced a filled house. Worse, the group's stroke-width="2" shadowed the component's strokeWidth prop. The fix does two things:

Hoist the wrapper. If the root has exactly one <g> child that only carries presentation attributes (fill, stroke, stroke-width, line caps/joins), those move onto the root and the group is unwrapped. Now the root really says fill="none" stroke="currentColor", and strokeWidth defaults to the icon's own 2.
Check ancestors, not just the root. If a group can't be hoisted (say it also has a transform), any element inside a fill="none" or stroked group is left alone instead of being filled.

With both in place, filled icons recolor correctly and outline icons stay outlines, whichever way the SVG is structured.

One prop contract, eight frameworks

Every template lives in src/templates/ and shares helpers from _shared.js. The key design decision: every framework gets the same props.

Prop	Default	What it does
`size`	`1em`	Sets `width` and `height`
`color`	inherited	Applied as CSS `color` — which `currentColor` resolves to
`strokeWidth`	the icon's own value	Overrides stroke width when passed
`className` / `class`	—	Merged onto the root `<svg>`

Notice that color is applied through CSS color, not by forcing a fill. That one choice means color="red" recolors filled icons and outline icons without ever changing what kind of icon it is.

Here's what that contract looks like in each ecosystem:

React / Next.js — named + default export, optional TypeScript props type, and an RSC-safe variant (--framework next-rsc) with no hooks and no 'use client':

export function HomeIcon({ size = '1em', color, strokeWidth, className, style, ...props }: IconProps) {
  return (
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor"
         width={size} height={size} strokeWidth={strokeWidth}
         className={className} style={color ? { color, ...style } : style} {...props}>
      <path d="…" />
    </svg>
  );
}

Vue — a Single File Component with real typed props and inheritAttrs: false, forwarding everything else via v-bind="$attrs":

<template>
  <svg viewBox="0 0 24 24" :width="size" :height="size" :stroke-width="strokeWidth"
       :style="color ? { color } : undefined" v-bind="$attrs">
    <path d="…" />
  </svg>
</template>

Angular — a standalone component with @Input()s and a selector like icon-home:

@Component({ selector: 'icon-home', standalone: true, template: `<svg …>…</svg>` })
export class HomeIcon {
  @Input() size: string | number = '1em';
  @Input() color?: string;
}

Laravel Blade — @props([...]) with $attributes->merge(), used as <x-home-icon size="24" color="red" />.

Svelte — exported props plus $$restProps; class is aliased because it's a reserved word in JS.

Solid — JSX with splitProps so known props are separated from the rest.

Web Components — a framework-free custom element with Shadow DOM, observing size, color, stroke-width and class:

<script type="module" src="./icons/home.js"></script>
<icon-home size="32" color="tomato"></icon-home>

Getting the markup idiomatic per framework is where most of the subtle bugs hide. A few I had to handle in _shared.js and the templates:

React needs camelCase attributes (stroke-linecap → strokeLinecap, class → className, xlink:href → xlinkHref) — but only attribute names, never path data.
Angular embeds the SVG in a template literal, so backticks, backslashes and ${ inside the markup must be escaped.
Web Components embed the markup as a JS string, so it goes through JSON.stringify to survive quotes and newlines.
Custom element names must contain a hyphen — hence the icon- prefix.

And if none of the built-ins fit your codebase, drop a react.hbs, vue.ejs or svelte.js into a templatesDir and Relaxicons will use your template instead, passing it { iconId, pascal, kebab, svg, typescript }. Handlebars and EJS are lazy-required, so they're only needed if you actually use them.

Caching that respects the network

Listing collections and searching icons means hitting Iconify's metadata endpoints a lot. src/utils/cache.js makes that cheap and resilient:

Responses are cached as JSON in ~/.cache/relaxicons (override with RELAXICONS_CACHE_DIR).
Each entry stores the ETag; the next request sends If-None-Match, and a 304 Not Modified just refreshes the timestamp.
Entries without an ETag use a 24-hour TTL.
Requests retry with backoff (250 ms → 500 ms → 1 s) on network errors, 429 and 5xx, and honour the server's Retry-After header.
If the network fails entirely, it falls back to stale cache instead of crashing.
RELAXICONS_OFFLINE=1 makes the CLI run purely from a warm cache — handy on a plane, and essential for deterministic tests.

relaxicons update-cache   # warm everything
relaxicons cache-clear    # start fresh

The small details that make a CLI pleasant

Most of the work in a CLI isn't the happy path — it's everything around it.

"Did you mean…?" — typo an icon name and Relaxicons loads the collection and ranks names by similarity:

✖ Icon not found
Did you mean: alarm-clock, alarm-check, alarm-off?

If nothing in that collection is close, it searches across collections for the nearest match.

Framework auto-detection — init looks for next.config.*, vite.config.* + a react/vue/svelte dependency, angular.json, or composer.json + artisan. Each match carries a confidence score and the highest wins (Astro is detected at low confidence so a docs folder never overrides your real app).

Always-sorted barrels — every add appends an export and re-sorts the barrel alphabetically, preserving comment headers and the file's original line endings (CRLF stays CRLF on Windows).

Batch-friendly errors — in a batch, a missing icon or an existing file doesn't abort the run; it's reported and the rest continue.

Meaningful exit codes, so scripts can react:

Code	Meaning
`0`	OK
`1`	Generic error
`2`	Config missing / invalid
`3`	Fetch failed
`4`	File already exists

And the usual polish: --dry-run to preview writes, --quiet and --no-color for CI logs, --raw for plain SVG, --both for component + cleaned SVG side by side, doctor to check Node, config and Iconify reachability, and a JSON Schema (relaxicons.config.schema.json) so your editor autocompletes the config.

Icons in CI

For teams, I wanted icons to be reproducible. List the icons your app uses in a manifest:

# relaxicons.manifest
lucide:home
lucide:star
mdi:github

…and regenerate them anywhere:

relaxicons regenerate -m relaxicons.manifest --concurrency 4

One fun bug from building this: the first version ran several add commands concurrently inside the same process by re-parsing the shared Commander instance. Commander keeps per-invocation state on that object, so parallel runs corrupted each other. The fix was to run each add in an isolated child process with a small worker pool — boring, but bulletproof.

The repo ships a ready-made GitHub Action that runs on changes to the manifest or config, regenerates the icons and commits the result:

- run: npm i -g relaxicons
- name: Regenerate icons
  run: relaxicons regenerate -m relaxicons.manifest
- name: Commit changes
  run: |
    git add -A
    git diff --cached --quiet || git commit -m "chore(relaxicons): regenerate icons"
    git push

The docs site

The documentation at ravikisha.github.io/relaxicons is built with Astro 5, React islands, Tailwind CSS 4 and Radix UI primitives, and deployed to GitHub Pages by the CI workflow on every push to main.

Some highlights:

Icon Explorer — browse collections, search icons, keep Favorites and Recent tabs, navigate with arrow keys + Enter, and copy an icon as a CLI command, raw SVG or data URI. It also shows per-collection stats and a top-icons carousel.
Command palette (built with cmdk) for jumping anywhere in the docs.
Copy-ready code tabs for every framework, an animated framework marquee and a live mini demo on the home page.

Good starting points in the docs:

Testing

The project has 24 Jest suites covering each piece in isolation and the CLI end to end:

Unit tests for naming, sanitizing, path handling, framework detection, config validation, the SVG transform, and every framework template.
Golden tests that snapshot generated output, so a template change can't silently alter what users get.
Integration tests that spawn the real CLI in temp directories with RELAXICONS_OFFLINE=1 and fixture icons — no network, no flakiness — and assert on files written and exit codes.
Windows path tests, because a CLI that writes files had better work with backslashes too.

npm test
npm run coverage

What I learned

SVG is not one format, it's a family of conventions. Outline vs. filled, attributes on the root vs. on a <g>, fill="none" meaning "inherit nothing". Normalizing icons from 200+ sets is way subtler than "replace the color", and testing against the real API response (not a hand-written fixture) is what caught the <g> wrapper bug.
Generating code means respecting each framework's idioms. It's easy to produce something that renders; it's harder to produce something a React, Vue or Angular developer would actually want to commit.
Caching is a UX feature. ETags, TTLs, backoff and stale fallback are what make a network-backed CLI feel instant and never strand you offline.
Shared mutable state bites, even in a CLI. The Commander concurrency bug was a good reminder that "it's just a script" doesn't exempt you from isolation.
Exit codes and --dry-run are documentation. They tell scripts and humans exactly what happened.

What's next

Real shell completions for zsh/bash/fish (the completion command is still a stub).
Removing the deprecated list alias in v2.0 (use icons instead).
More framework targets and richer custom-template examples.

If you're tired of juggling icon packages, give it a spin:

npm install -g relaxicons
relaxicons init
relaxicons add lucide:sparkles

⭐ Star it on GitHub, grab it from npm, and if you find an icon that renders wrong, open an issue — I'd love to see it.

Happy building! 🎨

How RelaxCSS Works: Building a TailwindCSS-Like Utility Engine

Ravi Kishan — Tue, 24 Jun 2025 05:59:38 +0000

Overview and Introduction

RelaxCSS is a lightweight, Tailwind-inspired utility-first CSS engine implemented as a PostCSS plugin and CLI tool. Like Tailwind, it provides a rich set of pre-defined utility classes (e.g. p-4, bg-blue-500, hover:text-white) and a configuration-driven design system. RelaxCSS aims to be minimal and extensible: it supports custom theme values (colors, spacing, etc.), responsive and pseudo-class variants, JIT compilation of only used utilities, and a plugin API for adding new utilities. Under the hood, a “preflight” (CSS reset) is injected (similar to Tailwind’s) and directives like @apply and @relax in CSS enable class composition.

In practice, you install RelaxCSS, write your CSS/HTML with utility classes, and run the CLI (or PostCSS plugin) to watch your files. The tool scans source files for class names (using glob patterns and regex), generates the corresponding utility CSS on-the-fly (JIT), and writes out a final output.css. The default configuration (which you can customize via relaxcss.config.js) includes sensible defaults for colors, spacing, screens, etc., and even a built-in example plugin (adding a fancy-border utility). Overall, RelaxCSS provides a Tailwind-like workflow—class-heavy markup and zero custom CSS—while remaining small and easy to extend.

Architecture Overview

RelaxCSS consists of several major components that work together in a build pipeline:

CLI/Watcher: A command-line interface (cli.ts/cli-watch.ts) runs RelaxCSS. It uses glob and chokidar to watch source files (HTML, CSS, JS, etc.) and trigger rebuilds on changes.
File Scanner (JIT Engine): The CLI watches file patterns (e.g. src/**/*.{html,js,jsx,ts,tsx,css}), reads each file’s content, and extracts class names with regex.
PostCSS Parser: RelaxCSS is implemented as a PostCSS plugin. The plugin receives the CSS AST parsed from your combined stylesheet (including your @apply rules).
Theme/Config: User configuration (from relaxcss.config.js or plugin options) is merged with the default theme/variants. This config object (colors, spacing, screens, etc.) is provided to the plugin and to any utility-generating code.
Utility Generator (Plugin Logic): The core plugin takes each utility class name (or @apply directive) and generates the corresponding CSS declarations based on the theme config. It supports responsive prefixes (e.g. md:), pseudo-classes (e.g. hover:), and even arbitrary values (bg-[#222]).
Output Generator: After PostCSS transforms (including preflight injection and @apply resolution), the plugin emits the final CSS. The CLI then writes this CSS to the output file (e.g. dist/output.css).

In this flow, the CLI initiates file scanning (with glob and chokidar) and combines CSS and @apply rules. The PostCSS parser parses the CSS, and the RelaxCSS plugin transforms it: injecting base styles (preflight), resolving @apply by inlining utility declarations, and wrapping rules in media/pseudo selectors. The theme/config drives which CSS values get used. Finally, the Output Generator writes out the CSS file.

Theme and Configuration System

RelaxCSS is highly configurable via a relaxcss.config.js (or via plugin options). The user config can define custom theme values (colors, spacing, fonts, etc.), responsive breakpoints, variants (e.g. which pseudo-classes to enable), plugins, and more. Internally, RelaxCSS starts with a defaultConfig (built-in) and merges the user’s config into it using lodash.merge:

const mergedConfig = merge(defaultConfig, opts);

This merged config object, mergedConfig, contains all theme scales. For example, the default theme includes a screens section (for breakpoints) and a spacing section:

theme: {
  screens: { sm: "640px", md: "768px", lg: "1024px", xl: "1280px" },
  spacing: { px: "1px", 0: "0px", 1: "0.25rem", 2: "0.5rem", … },
  colors: { transparent:"transparent", white:"#fff", blue: {50:"#eff6ff", 100:"#dbeafe", …}, … },
  fontSize: { base:["1rem",{lineHeight:"1.5rem"}], xl:["1.25rem",{lineHeight:"1.75rem"}], … },
  // etc.
}

Within the plugin code, CSS generation functions access these theme values. For example, when handling max-w-<key> utilities, the code does:

if (className.startsWith("max-w-")) {
  const value = get(config.theme.maxWidth, suffix);
  if (value !== undefined)
    declarations.push(new Declaration({ prop: "max-width", value }));
}

Similarly, for font sizes (text-xl), it retrieves a tuple from config.theme.fontSize:

const fontSizeTuple = get(config.theme.fontSize, suffix);
if (Array.isArray(fontSizeTuple)) {
  declarations.push(new Declaration({ prop: "font-size", value: fontSizeTuple[0] }));
  if (fontSizeTuple[1]?.lineHeight) {
    declarations.push(new Declaration({ prop: "line-height", value: fontSizeTuple[1].lineHeight }));
  }
}

In summary, RelaxCSS loads user settings (via opts or a relaxcss.config.js), merges them with defaults, and then all parts of the system read from this mergedConfig.theme. The variants section (e.g. which media queries and which pseudo-classes to support) also comes from the config and drives how the plugin wraps utility rules for sm: or hover: prefixes.

Utility Parser and Generator

At the heart of RelaxCSS is the utility parser, which takes a class name like p-4, bg-[#222], or md:hover:bg-blue-500 and translates it into one or more CSS declarations. This logic lives in the function generateUtilityCss(className, config) in index.ts. The class name is split into a prefix (e.g. p, bg, text, etc.) and a suffix (the part after the dash). A series of if/else and switch statements handle each utility:

Spacing utilities (p-4, mt-2, mx-auto, etc.): use helper functions that look up the numeric key in config.theme.spacing and emit corresponding padding or margin declarations. For example, m-4 becomes margin: 1rem if spacing[4] = "1rem".
Size limits (max-w-lg, max-h-full): look up in config.theme.maxWidth or maxHeight (from the merged config) and emit max-width or max-height. See above in .
Colors and fonts: for text-<color>-<shade> or bg-<color>-<shade>, a helper (getColor) checks the nested config.theme.colors. For text-xl, it instead looks in config.theme.fontSize as shown in .

Importantly, RelaxCSS also supports arbitrary values via a special parser function. A class like bg-[#222] or p-[4px] matches the regex /^([a-z-]+)-\[(.+)\]$/. This extracts a prefix and a raw value. The code parseArbitraryValue(className, config) (see below) directly maps certain prefixes to CSS properties:

function parseArbitraryValue(className: string, config: RelaxConfig): Declaration[] {
  // e.g. bg-[#222], p-[4px], text-[red], w-[100px], m-[1rem], etc.
  const arbitraryMatch = className.match(/^([a-z-]+)-\[(.+)\]$/i);
  if (!arbitraryMatch) return [];
  const prefix = arbitraryMatch[1];
  const value = arbitraryMatch[2];
  // Map prefix to CSS property
  switch (prefix) {
    case "bg":
      return [new Declaration({ prop: "background-color", value })];
    case "text":
      return [new Declaration({ prop: "color", value })];
    case "border":
      return [new Declaration({ prop: "border-color", value })];
    case "w":
      return [new Declaration({ prop: "width", value })];
    case "h":
      return [new Declaration({ prop: "height", value })];
    // ... handle px, py, m, etc. in a similar way ...
    default:
      // fallback: treat prefix as the property name
      return [new Declaration({ prop: prefix, value })];
  }
}

When the PostCSS plugin encounters a utility class, it first tries parseArbitraryValue. If that returns declarations, it uses them directly (for example, bg-[#222] yields background-color: #222). Otherwise, it falls back to the standard generateUtilityCss logic for named utilities.

Responsive and pseudo variants: Class names can be prefixed with media queries or pseudo-classes, like sm:, md:, hover:, focus:, etc. In RelaxCSS this is handled in the plugin as well. The CLI/JIT will detect a class like md:hover:bg-blue-500 and enqueue it. The plugin code splits on ":" to see that md is a responsive variant and hover is a pseudo-variant, and then wraps the generated declarations accordingly. For example, md:hover:bg-blue-500 results in a rule inside a @media (min-width: 768px) block, with selector .md\:hover\:bg-blue-500:hover { background-color: ... }. (The plugin has helper code to do this, but the key point is that our design allows stacking variants in class names.)

For standard utilities (without variants), the code essentially turns a class into a CSS rule of the form .<class> { <declarations> }. For example, text-xl would lead to:

.text-xl {
  font-size: 1.25rem; /* from theme */
  line-height: 1.75rem; /* from theme */
}

Likewise, .bg-blue-500 { background-color: #3b82f6; }. Arbitrary values work similarly: .bg-\[\#222\] { background-color: #222; }.

Plugin System

RelaxCSS provides a plugin API so users can register additional utilities. A plugin is simply a function receiving an API object, e.g.:

interface RelaxPlugin {
  (api: {
    addUtilities: (utils: Record<string, (config: RelaxConfig) => Declaration[]>) => void;
    config: RelaxConfig;
  }): void;
}

Within this function, a plugin typically calls api.addUtilities(...) with new utility definitions. For example, the default config includes a built-in plugin that adds a fancy-border utility:

plugins: [
  function ({ addUtilities, config }) {
    addUtilities({
      "fancy-border": () => [
        // This utility generates: border:2px dashed magenta;
        new Declaration({ prop: "border", value: "2px dashed magenta" }),
      ],
    });
  },
],

After loading the config, RelaxCSS iterates through any plugins array (if provided) and calls each plugin function. The addUtilities calls aggregate into a userUtilities map. Later, during CSS generation, these custom utilities are treated just like built-in ones: if a class matches "fancy-border", RelaxCSS will output the declarations given by that plugin function.

This plugin mechanism allows anyone to extend RelaxCSS with their own custom shortcut classes (e.g. new color utilities, or even complex components) without modifying the core engine.

JIT Compilation and File Scanning

The CLI tool (cli-watch.ts) implements a Just-In-Time (JIT) engine. Instead of generating all possible utility classes, it scans your source files on-the-fly for exactly the classes you use. Key points:

File watching: The CLI takes a glob pattern like src/**/*.html and uses glob.sync to find matching files. It then sets up a watcher with chokidar.watch(srcGlob) to re-run the scan whenever any matching file changes. This makes it incremental and efficient.
Class extraction: For each source file, the code reads its contents and uses a regex to find class names. For HTML/JSX/etc, it matches class="...", className="...", or Vue :class="...", etc. The regex used is:
```
const classRegex = /(?:class|className|:class)\s*=\s*["'`\{[]([^"'`\}\]]+)["'`\}]/g;
```
Then it splits the captured class string on whitespace. For example, in <div class="text-xl p-4 hover:bg-red-500">, it will extract ["text-xl","p-4","hover:bg-red-500"].

CSS files are also scanned for @apply directives: another regex /@apply\s+([^;]+);/g pulls out any classes listed in an @apply statement.
Building CSS to apply: After scanning all files, the CLI builds a temporary CSS string where each found class is “applied” via @apply. For example, if it found text-lg and mt-4, it generates:
```
.text-lg { @apply text-lg; }
.mt-4 { @apply mt-4; }
```
(It also handles variants by calling a helper generateTailwindVariantRule, but ultimately it creates @apply rules for each used class.) This combined CSS (plus any raw CSS content) is then fed into PostCSS with the RelaxCSS plugin.
Automatic rebuilds: Thanks to chokidar, any file change triggers the scan-and-build process again. This ensures the output CSS is always up-to-date with the classes in your source.

Key code excerpts from cli-watch.ts:

// Scan files for classes and @apply
const files = glob.sync(srcGlob);
console.log(`[RelaxCSS] Processing files matching: ${files}`);
files.forEach((file) => {
  const ext = path.extname(file).slice(1);
  const content = fs.readFileSync(file, "utf8");
  if (ext === "css") {
    combinedCss += content + "\n";
    extractApplyClasses(content).forEach(cls => foundClasses.add(cls));
  } else if (fileExtensions.includes(ext)) {
    extractClassNames(content).forEach(cls => {
      foundClasses.add(cls);
      classNameFoundClasses.add(cls);
    });
  }
});

The extractClassNames and extractApplyClasses functions use regexes to find classes:

// In cli-watch.ts:
function extractClassNames(content: string): string[] {
  // Match class="...", className="...", etc.
  const classRegex =
    /(?:class|className|:class)\s*=\s*["'`\{[]([^"'`\}\]]+)["'`\}]/g;
  let match;
  while ((match = classRegex.exec(content))) {
    matches.push(...match[1].split(/\s+/).filter(Boolean));
  }
  return matches.filter(cls => !cls.startsWith("...")); // ignore Spread syntax
}

After extracting, the watcher rebuild logic looks like:

// Watch for changes and rebuild
const watcher = chokidar.watch(srcGlob, { ignoreInitial: true });
watcher.on("all", (event, filePath) => {
  console.log(`[RelaxCSS] Detected ${event} in ${filePath}. Rebuilding...`);
  processFiles();
});

This JIT pipeline – scan source → extract classes → generate @apply CSS → run RelaxCSS plugin – ensures that only used utilities end up in the final CSS. We can diagram it as:

Preflight and CSS Output

By default, RelaxCSS injects a small preflight (base reset) at the top of the CSS. This is similar to Tailwind’s Preflight and is meant to normalize browser defaults. In the plugin code, you can see it defines sections like “box-sizing”, “margin-padding”, “list-style”, etc.:

const preflightSections: Record<string, string> = {
  "box-sizing": `*,*::before,*::after{box-sizing:border-box;}`,
  "margin-padding": `body,h1,h2,h3,h4,h5,h6,p,ul,ol,li,figure,figcaption,blockquote,dl,dd{margin:0;padding:0;}`,
  "list-style": `ul:not([class]),ol:not([class]){list-style:none;}`,
  "font-family": `body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,Cantarell,"Open Sans","Helvetica Neue",sans-serif;line-height:1.5;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;}`,
  "media": `img,picture,video,canvas,svg{display:block;max-width:100%;}`,
  "form": `button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0;}`,
  "table": `table{border-collapse:collapse;}th,td{padding:0;}`,
};

These CSS snippets (with comments like /* RelaxCSS Preflight: box-sizing */) are prepended to the output. The preflight section of the config allows enabling/disabling parts or adding overrides, but by default all sections are included. For example, the first injected rule is *,*::before,*::after{box-sizing:border-box;} (ensuring consistent box-sizing).

After the plugin runs (resolving all @apply rules into concrete declarations and wrapping variants), the final CSS is emitted. In cli-watch.ts, this is done with PostCSS:

postcss([ relaxcss() ])
  .process(finalCss, { from: undefined })
  .then((result) => {
    fs.mkdirSync(path.dirname(outFile), { recursive: true });
    fs.writeFileSync(outFile, result.css, "utf8");
    console.log(`[RelaxCSS] Rebuilt: ${outFile}`);
  })
  .catch((err) => console.error("[RelaxCSS] Build error:", err));

So the final output is a single CSS file that begins with the preflight rules, followed by your combined utilities. All @apply rules have been replaced by their actual CSS declarations. For instance, if you had:

@relax;
.container { @apply flex bg-[#222] md:hover:bg-[#333]; }

the output might look like:

/* RelaxCSS Preflight: box-sizing */
*,*::before,*::after{box-sizing:border-box;}
/* RelaxCSS Preflight: margin-padding */
body,h1,...,dd{margin:0;padding:0;}
/* ... other preflight rules ... */

/* Utility classes */
.container {
  display: flex;
  background-color: #222;
}
@media (min-width:768px) {
  .md\:hover\:bg-\[\#333\]:hover {
    background-color: #333;
  }
}

In the example above, .container got display:flex (from the flex utility) and background-color:#222 (from bg-[#222]). The md:hover:bg-[#333] utility generated a media query rule for screens >=768px with the selector .md:hover:bg-[#333]:hover.

Example Output and Live Usage

Suppose we have an input CSS file like src/input.css:

/* src/input.css */
@relax;

.container {
  @apply flex bg-[#222] md:hover:bg-[#333];
}

.my-box {
  @apply fancy-border;
}

.ravi {
  @apply text-2xl;
}

.kishan {
  @apply text-3xl;
}

Here we use @relax; to trigger the plugin, and we apply several utilities:

flex, bg-[#222], and md:hover:bg-[#333] on .container.
fancy-border on .my-box (this was a custom utility from the default plugin).
text-2xl and text-3xl on .ravi and .kishan.

Running RelaxCSS on this (npx ts-node src/cli-watch.ts "src/**/*.{css,html,js,jsx,ts,tsx}" --out dist/output.css) will produce a dist/output.css roughly like:

/* RelaxCSS Preflight: box-sizing */
*,*::before,*::after{box-sizing:border-box;}
/* RelaxCSS Preflight: margin-padding */
body,h1,h2,h3,h4,h5,h6,p,ul,ol,li,figure,figcaption,blockquote,dl,dd{margin:0;padding:0;}
/* ... other preflight rules ... */

.container {
  display: flex;
  background-color: #222;
}
@media (min-width:768px) {
  .md\:hover\:bg-\[\#333\]:hover {
    background-color: #333;
  }
}
.my-box {
  border: 2px dashed magenta;
}
.ravi {
  font-size: 1.5rem;
  line-height: 2rem;
}
.kishan {
  font-size: 1.875rem;
  line-height: 2.25rem;
}

For live usage, one might have an HTML file like:

<button class="m-4">
  <span class="hover:bg-blue-500 hover:text-white md:hover:bg-blue-700 bg-[#222]">
    Hover over me
  </span>
</button>

When RelaxCSS processes this (in JIT mode), it will generate the equivalent CSS so that the button responds to hover and changes background/text color as expected.

Conclusion

RelaxCSS is a compact, flexible framework for utility-first styling, suitable for frontend developers and framework authors who want Tailwind-like productivity with a smaller footprint. It leverages a PostCSS plugin to parse utility class names (p-4, text-blue-500, hover:bg-red-200, etc.) and emit the corresponding CSS using values from a theme configuration. The CLI/JIT engine watches your files and includes only the utilities you actually use, keeping the CSS minimal. The plugin system lets you define your own utilities or copy Tailwind’s plugin approach. By supporting arbitrary values (bg-[#222]), responsive prefixes (md:) and variants (hover:), plus a built-in preflight reset, RelaxCSS covers most needs of modern utility-based development.

For advanced use, you can extend RelaxCSS by adding more functions to generateUtilityCss, writing plugins with addUtilities, or customizing the configuration. Because it’s just a PostCSS plugin and Node script, you could even integrate it into larger build tools or frameworks. Overall, RelaxCSS aims to be a learning-friendly, extensible alternative to Tailwind for projects where you want control over the utility engine’s internals. Users can build on this foundation – for example, adding support for more CSS features or improving performance – thanks to its clear architecture.

Sources: The above explanations and code snippets are drawn directly from the RelaxCSS source files (e.g. index.ts, cli-watch.ts, base.css).

Ravikisha / RelaxCSS

A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support. RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

RelaxCSS

A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support.

RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

PostCSS Plugin Usage

RelaxCSS is a drop-in PostCSS plugin. It works with PostCSS v8+ and integrates with any PostCSS-based build system (Webpack, Vite, Parcel, etc).

// postcss.config.js
const relaxcss = require('relaxcss');

module.exports = {
  plugins: [
    require('postcss-import'), // must be first
    relaxcss({
      // custom config here
    }),
    require('autoprefixer'),
    // ...
  ]
};

Supports all RelaxCSS features: JIT utilities, plugins, variants, dark mode, RTL, CSS variables, and more.
Use your relaxcss.config.js for custom configuration.
Compatible with PostCSS v8+ and all major build…

View on GitHub

npmjs.com

Building a Container Runtime from Scratch with Go (MyDocker)

Ravi Kishan — Thu, 05 Jun 2025 13:25:34 +0000

Table of Contents

Introduction: What is a Container Runtime?
Namespaces: Isolating Processes on Linux
Control Groups (cgroups): Managing Resources
Project Architecture: The MyDocker Design
- Command-Line Interface and Main.go
- Container Lifecycle (startContainer, child)
- Networking Isolation (Bridge and veth)
- Image Handling and OCI Unpacking
- Volumes and Port Mappings
Diagrams: Visualizing the Runtime
Getting Started and Resources

Introduction

Containers are lightweight, isolated environments for running applications. Unlike virtual machines, containers share the host kernel but isolate processes using kernel features like namespaces and cgroups. In this tutorial we’ll explore MyDocker, a simple container runtime written in Go, and walk through the key pieces that make it work. We’ll explain how MyDocker uses Linux namespaces (UTS, PID, network, mount, etc.) to isolate the container’s view of the system, and how it uses cgroups to limit resources. Along the way we’ll show key code snippets (e.g. startContainer, child, execContainer) and outline MyDocker’s architecture for CLI commands, networking, and image handling. By the end, you’ll see how MyDocker’s internals fit together, and how OCI image unpacking with tools like umoci and simple mount/iptables tricks provide the functionality of docker pull, run, exec, and more. We encourage you to check out the [MyDocker GitHub repository][22] and its [README][26] for examples and to try extending the code yourself.

Namespaces

Linux namespaces provide isolation by giving a process its own “view” of system resources. For example, PID namespaces mean a process can see only processes in its own container; UTS namespaces let each container have its own hostname; mount namespaces give each container its own filesystem root; network namespaces provide separate network interfaces/iptables, and so on. In other words, namespaces prevent processes in one container from seeing or affecting those in another. This isolation is a cornerstone of container security: “namespaces are quite flexible…they can be applied individually or in groups to one or more processes”. MyDocker’s container “child” process is created with clone flags for multiple namespaces (UTS, PID, NET, mount, etc.), so it runs in isolation. The code roughly follows the pattern:

// In main or run command:
cmd := exec.Command("/proc/self/exe", append([]string{"child"}, os.Args[2:]...)...)
cmd.SysProcAttr = &syscall.SysProcAttr{
    Cloneflags: syscall.CLONE_NEWUTS |
                syscall.CLONE_NEWPID |
                syscall.CLONE_NEWNET |
                syscall.CLONE_NEWNS, // etc.
}
cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
must(cmd.Run())

// The child() function runs inside the new namespaces:
func child() {
    // e.g., set hostname inside UTS namespace
    syscall.Sethostname([]byte("mydocker"))
    // Possibly mount proc, chroot, pivot_root, etc.
    // Finally exec the requested command:
    cmd := exec.Command(os.Args[2], os.Args[3:]...)
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    must(cmd.Run())
}

As in other “container-from-scratch” examples, this pattern uses exec.Command("/proc/self/exe", "child", …) to re-invoke the same program in a new process (in new namespaces). From outside, the run command spawns the namespaced child; inside the container, the child function does setup (hostname, filesystem mounts, etc.) and then executes the user’s command. This effectively gives the container its own isolated environment separate from the host.

Figure: Container runtime architecture. MyDocker creates a namespaced “child” process for each container, mounts a fresh root filesystem (unpacked from an OCI image), applies cgroup limits, and sets up networking (bridge mydocker0 and veth pair). The CLI (main.go) drives commands like run, exec, pull, etc.

In summary, namespaces ensure that processes in MyDocker containers see only their own CPU, memory, filesystems, networks, and process list. This is one of the fundamental layers of container isolation. (MyDocker’s README also highlights this as a core feature: “Container process isolation using Linux namespaces (UTS, PID, NET, MNT)”.)

Control Groups (cgroups)

While namespaces isolate what a process sees, cgroups control how much of a resource a process can use. A control group (cgroup) is a Linux kernel feature that limits, accounts for, and isolates resource usage (CPU, memory, I/O, etc.) of a group of processes. MyDocker uses cgroups so that each container process has its own CPU and memory limits (as defined by CLI flags). For example, it might create a new cgroup under /sys/fs/cgroup/cpu/mydocker/<id> and write the PID of the container process into it, along with any limits (like cpu.shares or memory.limit_in_bytes). This means the container will only get a fraction of CPU or a fixed amount of memory, protecting the host and other containers.

“Cgroups are a kernel feature that allows you to partition and limit the system resources… that a group of processes can use. Think of them as virtual cages where you can corral your processes and set rules for their behavior”. (This quote describes cgroups in general; MyDocker uses them specifically for CPU and memory limits.)

For instance, MyDocker might contain code like:

// Simplified: create a cpu cgroup for the container
cgroupPath := filepath.Join("/sys/fs/cgroup/cpu/mydocker", containerID)
os.MkdirAll(cgroupPath, 0755)
// write the container's PID into the cgroup.procs file
os.WriteFile(filepath.Join(cgroupPath, "cgroup.procs"), []byte(pidStr), 0644)
// optionally set limits like cpu.shares or memory.limit_in_bytes

This ensures each container is “in its own cage”. The MyDocker README emphasizes resource control: “Resource control via cgroups (CPU & Memory)”. By combining cgroups with namespaces, the runtime isolates both the view and resources of each container process, similarly to how Docker does it behind the scenes.

Project Architecture

MyDocker’s source is structured simply (see [Architecture Overview][100]). At the top level we have:

main.go – The CLI entry point: parses commands like run, exec, pull, etc. It calls functions like startContainer() or execContainer() accordingly.
cgroups/ – Go package to set up cgroup directories and limits.
network/ – Go package to create a bridge (mydocker0) and virtual ethernet (veth) pairs for container networking.
helper.c – A small C program that is used to join existing namespaces (see below).
Other files: e.g. configuration templates, documentation.

The architecture overview in the README summarizes this:

“Architecture Overview: main.go — The CLI and container runtime entry point; cgroups/ — resource limits; network/ — bridge networks/veth; /var/lib/mydocker/ — stores metadata/images”.

So when you run something like sudo ./mydocker run -v /data:/data -p 8080:80 ubuntu:22.04 sh, what happens? A brief walkthrough:

CLI (main.go): The program parses the run command and container options (image name, mounts, ports, etc.). It likely calls a function startContainer(containerID, command, flags...).
startContainer: This function creates a unique container ID, sets up storage (image unpack, rootfs), sets up networking, then spawns a child process in new namespaces (using exec.Command("/proc/self/exe", ...) as above). It also records container metadata (like PID, rootfs path) under /var/lib/mydocker/.
Child process: In the new namespaces, it does further initialization: e.g., performs chroot/pivot_root into the unpacked image root filesystem; mounts the host directory if -v was given; configures networking (calls net.SetupVeth() to move one end of a veth into this namespace); then finally execs the user’s command (e.g. sh).
Networking: The network/ code ensures there is a Linux bridge (e.g. mydocker0) on the host. It creates a veth pair, moves one end into the child’s net namespace (as eth0), and attaches the other end to the mydocker0 bridge, giving the container network access (with its own IP).
Cgroups: Concurrently, before or after spawning the child, MyDocker creates new cgroup entries under CPU/memory controllers and adds the child’s PID, enforcing resource limits on that container.
Image Unpacking: For pulling images, MyDocker uses umoci. The pull command downloads an OCI image (like Ubuntu) and uses umoci unpack to extract it into a directory under /var/lib/mydocker. Umoci documentation explains: “umoci unpack - Unpacks an OCI image tag into a runtime bundle”. In other words, MyDocker relies on umoci to convert a container image into a rootfs directory with config, just like Docker does with layered filesystems.

Command-Line Interface and Main.go

The main.go file defines the CLI commands (run, exec, ps, etc.) using a library like urfave/cli. For example, when the user runs mydocker run ..., it ends up invoking something like:

func runCommandAction(ctx *cli.Context) error {
    imageName := ctx.Args().Get(0)
    cmd := ctx.Args().Get(1)
    flags := ctx.GlobalFlags()
    containerID := generateID()
    startContainer(containerID, imageName, cmd, flags)
    return nil
}

The core functions include startContainer (for run) and ExecContainer (for exec). In MyDocker, startContainer will unpack the image if needed, set up cgroups/networks, then clone a new process.

The execContainer function (called by mydocker exec) is also interesting. It finds the PID of an existing container process (by reading stored metadata) and then uses exec.Command("/proc/self/exe", "exec") to fork a helper process that enters that container’s namespaces (via a small C helper). Part of the code might look like:

func ExecContainer(containerID string, comArray []string) {
    pid, err := getPidByContainerId(containerID)
    // Set environment variables for the helper C program:
    cmd := exec.Command("/proc/self/exe", "exec")
    os.Setenv("mydocker_pid", pid)
    os.Setenv("mydocker_cmd", strings.Join(comArray, " "))
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    cmd.Run()
}

This tells the re-invoked process to run the "exec" branch of main(). The helper C code (in helper.c) sees mydocker_pid/mydocker_cmd and performs setns() calls to join the PID/UTS/NET namespaces of that container, then uses system(mydocker_cmd) to run the desired command inside the container. (In effect, mydocker exec adds your shell to the existing container’s namespaces, letting you run commands inside it.) The Chinese blog [89] illustrates this pattern clearly. The key idea is: we fork a new process that points itself into the container’s namespaces and execs the command as if we were inside the container.

Container Lifecycle (`startContainer`, `child`)

Putting it all together, MyDocker’s container lifecycle roughly is:

Start: User runs mydocker run .... The Go main.go calls startContainer(...).
Setup: In startContainer, MyDocker creates a directory for the container under /var/lib/mydocker/<id>. It unpacks the OCI image rootfs there (if not done already), creates cgroups, sets up network (bridge/veth), and prepares the command arguments.

Clone (run): The code then does something like:

cmd := exec.Command("/proc/self/exe", append([]string{"child"}, commandArgs...)...)
cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
cmd.SysProcAttr = &syscall.SysProcAttr{
    Cloneflags: CLONE_NEWUTS | CLONE_NEWPID | CLONE_NEWNET | CLONE_NEWNS,
    UidMappings: ...,
    GidMappings: ...,
}
cmd.Run() // blocks until container process exits

This effectively forks into a child process that will run mydocker child ....

Child setup: In the child() function inside Go, the process is now in fresh namespaces. It performs actions similar to Docker’s container init:

- Calls `syscall.Chroot()` or `pivot_root()` to switch the root filesystem to the unpacked image.

- Applies mounts and volume binds (`syscall.Mount()`) for any `-v host:container` flags.

- Calls `net.SetupVeth()` to move one end of the veth into this namespace and bring up the network interface.

- Executes the container’s init process (e.g., `exec.Command("/bin/sh")`).

Run: The container process (PID 1 in its PID namespace) starts and runs user code. Meanwhile, the parent Go process (still the original CLI) waits (or returns immediately if detached).
Stop: When the container’s main process exits (e.g. you exit the shell), the child function returns. startContainer (the parent) will then do cleanup: remove cgroups, delete metadata, etc.

The code for startContainer and child in MyDocker is similar in spirit to many "from-scratch Docker" examples (e.g. [86]). For instance, the parent uses exec.Command("/proc/self/exe", "child", …) to create the child. Inside child, Go code uses syscalls (Mount, Chroot, Sethostname, etc.) to finish setting up the namespace, then exec.Command to run the actual command. Though we can’t cite the MyDocker source directly here, conceptually it follows the pattern above.

Networking

By default, containers should be able to talk to each other and the outside world (on certain ports). MyDocker’s network/ package likely does the following (in Go, via the vishvananda/netlink library or raw syscalls):

Ensure a Linux bridge exists (named mydocker0). If not, create it with ip link add name mydocker0 type bridge.
For each new container, create a veth pair (e.g. veth-host and veth-container). Move veth-container into the new namespace of the child (with netlink.LinkSetNsFd) and rename it to eth0.
Bring up eth0 inside the container and assign it an IP (e.g. via ip addr).
Attach veth-host to the mydocker0 bridge and bring it up on the host.

This way, containers get an IP on the mydocker0 network, and host-side NAT (iptables MASQUERADE) handles outbound traffic and port mapping. MyDocker’s README mentions a custom bridge network (mydocker0) and veth pairs for network isolation. (In our blog, we won’t go into all the iptables details, but that’s how host ports get forwarded: the CLI probably calls iptables -t nat rules so that -p host:container flags forward TCP from the host port to the container’s IP:port.)

Image Handling and OCI Unpacking

Container images (like ubuntu:22.04) come in the OCI/Docker image format. MyDocker supports pulling and unpacking these images using the umoci tool. The mydocker pull command likely shells out to umoci pull or similar, then umoci unpack. As the umoci manual states: “umoci unpack – Unpacks an OCI image tag into a runtime bundle”. In practice, MyDocker runs something like:

umoci unpack --image ubuntu:22.04 /var/lib/mydocker/images/ubuntu_22.04

This extracts the image layers and config into a directory that becomes the container’s root filesystem. MyDocker then stores this location (under /var/lib/mydocker/) so that future run commands can use the rootfs directly without repulling. The unpacked bundle includes /rootfs with all files and a JSON config. MyDocker’s Go code then chroot-es into that /rootfs when starting a container.

Using umoci (or a similar OCI utility) is important because it handles the layered filesystem format of images. Without overlay support, MyDocker unpacks into a single directory per image. The README cites “Simple OCI image unpacking using umoci” as a feature.

Volumes and Port Mappings

Volumes (-v): If the user specifies -v /host/dir:/container/dir, MyDocker will mount a bind mount inside the container namespace. The Go code in child() would do something like:

syscall.Mount("/host/dir", "/container/dir", "", syscall.MS_BIND, "")

after switching to the new root. This makes the host’s directory appear at the given path in the container. It relies on the mount namespace being isolated, so only the container sees the mount (the host’s filesystem is shared, but the namespace separates the mount list).

Port mappings (-p): For -p hostPort:containerPort, the runtime must forward network traffic. A simple approach: on the host, use iptables to NAT traffic from hostPort into the container’s IP and containerPort. For example:

iptables -t nat -A PREROUTING -p tcp --dport <hostPort> -j DNAT --to-destination <containerIP>:<containerPort>
iptables -t nat -A POSTROUTING -j MASQUERADE

This way, if a service inside the container listens on containerPort, requests to localhost:hostPort on the host will reach it. MyDocker’s implementation likely sets up such iptables rules automatically when starting the container, and removes them on stop. This achieves “port mapping” similar to Docker.

Diagrams

Below are some visual aids (using PlantUML) to illustrate the architecture and isolation concepts. These diagrams are simplified schematics.

These diagrams outline how the host CLI and services collaborate to create an isolated container process. In particular, the second diagram emphasizes that once the container process (C) is created, it has its own namespace instances and cannot see the host’s unrelated processes or network stacks.

Getting Started and Resources

MyDocker is intended as a learning tool to explore container internals. It “demonstrates how containerization works under the hood” and helps you understand namespaces, cgroups, and image formats. You can try it out by following the README instructions: for example, pull an image (mydocker pull ubuntu:22.04) and run it (mydocker run -it -v /data:/data -p 8080:80 ubuntu:22.04 bash) as shown in the usage examples. You’ll see your process isolated (check ps and hostname inside the container, and network connectivity to the bridge).

We encourage you to explore the Project Files (which includes source code and examples) and even extend it. Possible exercises include adding features like Dockerfile builds, overlayfs support, or enhanced networking. By tinkering with MyDocker’s code, you’ll gain a deep understanding of what happens in every docker run command. Happy hacking and containerizing!

Check out the github repo:

Ravikisha / MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

🐳 MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

👉 GitHub Repository

🚀 Features

Container process isolation using Linux namespaces (UTS, PID, NET, NS)
Resource control via cgroups (CPU & Memory)
Volume mounting (-v host:container)
Port mapping support (-p host:container)
Simple OCI image unpacking using umoci
Container image pulling, listing, and execution
Custom bridge network (mydocker0) and veth pairs for network isolation
Command-line interface similar to Docker (run, exec, ps, stop, pull, images, version)

🎯 Architecture

📦 Installation

Requirements

Go 1.19+

Root access (for namespace and networking)

umoci tool installed and in $PATH

Linux OS (recommended: Ubuntu)

git clone https://github.com/ravikisha/mydocker.git
cd mydocker
go build -o mydocker main.go
sudo ./mydocker version

…

View on GitHub

Introducing RelaxLang: A Beginner-Friendly Programming Language

Ravi Kishan — Thu, 16 Jan 2025 19:30:05 +0000

In the vast and ever-evolving world of programming languages, creating one from scratch is a feat that blends art, science, and a touch of magic. Today, I am excited to introduce RelaxLang, a simple yet powerful interpreted programming language. Inspired by Robert Nystrom's Crafting Interpreters and the Lox programming language, RelaxLang is designed to be accessible for beginners while being feature-rich for enthusiasts who want to dive deeper into language design and implementation.

Why RelaxLang?

RelaxLang stems from a vision to provide a lightweight, easy-to-understand programming language that serves as both a learning tool and a practical solution for basic scripting needs. Built with Java and C, it offers:

Dynamic Typing: Simplifies coding by inferring variable types at runtime.
First-Class Functions: Enables functional programming paradigms by treating functions as first-class citizens.
Classes and Inheritance: Introduces object-oriented programming with a straightforward syntax.
Built-In Standard Library: Provides out-of-the-box utilities for string manipulation, array operations, and more.

Whether you're an aspiring developer eager to learn how programming languages work or a seasoned programmer seeking an educational tool, RelaxLang caters to you.

Architecture

Key Features of RelaxLang

1. Dynamic Typing

In RelaxLang, you don’t need to worry about specifying types for variables. The interpreter takes care of it, allowing you to focus on logic and creativity.

var name = "RelaxLang";  // Automatically inferred as String
var version = 1.0;       // Automatically inferred as Float
var isActive = true;     // Automatically inferred as Boolean

print(name);            // Output: RelaxLang
print(version);         // Output: 1.0
print(isActive);        // Output: true

2. First-Class Functions

Functions are versatile in RelaxLang. They can be assigned to variables, passed as arguments, and even returned from other functions.

fun add(a, b) {
    return a + b;
}

var sum = add(5, 3);
print(sum);  // Output: 8

fun operate(func, x, y) {
    return func(x, y);
}

var result = operate(add, 10, 15);
print(result);  // Output: 25

3. Classes and Inheritance

RelaxLang supports object-oriented programming, making it a great tool to understand and implement OOP concepts.

class Animal {
    var name;

    init(name) {
        this.name = name;
    }

    fun speak() {
        print(this.name + " makes a sound.");
    }
}

class Dog < Animal {
    fun speak() {
        print(this.name + " barks.");
    }
}

var myDog = Dog("Buddy");
myDog.speak();  // Output: Buddy barks.

4. Control Flow

With intuitive if-else statements and loops, you can control the flow of your programs effortlessly.

var age = 18;

if (age < 18) {
    print("Minor");
} else {
    print("Adult");
}

for (var i = 0; i < 5; i = i + 1) {
    print(i);  // Output: 0 1 2 3 4
}

How to Get Started

1. Prerequisites

Ensure you have the following installed:

Java JDK 11 or later (Download here)
(Optional) Docker for a containerized setup

2. Installation

Clone the Repository:

git clone https://github.com/Ravikisha/RelaxLang.git
cd RelaxLang

Compile the Source Code:

javac src/*.java

3. Running RelaxLang

Using the JAR File:

java -jar lox.jar

Using Docker:

docker pull ravikishan63392/relaxlang:lastest
docker run -it ravikishan63392/relaxlang:lastest

Example Usage

RelaxLang scripts are simple to write and execute. For instance, here’s a script example.rl:

fun greet(name) {
    print("Hello, " + name + "!");
}

greet("World");

Run it with:

java -jar lox.jar example.rl

The Technical Journey

RelaxLang’s implementation involves:

Lexical Analysis: Breaking down source code into tokens.
Parsing: Constructing an Abstract Syntax Tree (AST) from tokens.
Interpreting: Executing the AST by traversing it node by node.

Developed in Java for platform independence and in C for low-level optimizations, RelaxLang’s design reflects a balance between simplicity and functionality.

Resources and Contributions

Docker Image:

RelaxLang Docker Image

GitHub Repository:

RelaxLang on GitHub

We welcome contributions! Whether it's bug fixes, feature requests, or documentation improvements, your input makes RelaxLang better. Please check out the contributing guidelines in the repository.

Final Thoughts

RelaxLang is not just a programming language; it’s a journey into the heart of language design. By exploring its features, experimenting with scripts, and diving into its implementation, you can gain insights into how modern programming languages work.

Give RelaxLang a try and embark on this exciting adventure. Let’s code, learn, and relax!

Building RelaxTube: A Scalable Video Transcoding and Streaming Application

Ravi Kishan — Tue, 14 Jan 2025 18:34:42 +0000

Introduction

RelaxTube is a feature-rich and scalable application designed to demonstrate the workflow of video transcoding and streaming. The project highlights the use of modern technologies like Node.js, React, Kafka, FFmpeg, MongoDB, and Docker. It efficiently processes videos by transcoding them into multiple quality levels, segmenting them for smoother streaming, and generating thumbnail previews.

This blog explores the architecture, key features, tech stack, installation, and potential enhancements for RelaxTube.

Key Features

Video Transcoding: Converts videos into multiple quality levels (360p, 480p, 720p, 1080p) using FFmpeg.
HLS Segmentation: Generates video segments for efficient HTTP Live Streaming (HLS) playback.
Thumbnail Generation: Automatically creates thumbnail previews for each uploaded video.
Batch Processing: Supports concurrent video processing using Kafka message queues.
Scalable Design: Built to handle increased loads and integrate with distributed systems.
Storage and Metadata: Manages video files in local storage and metadata in MongoDB.

Project Architecture

Components

Frontend (React): Provides a user-friendly interface for video uploads, management, and playback.
Backend (Node.js with Express): Handles API requests, video processing workflows, and communication with Kafka.
Kafka: Manages message queues for efficient batch processing.
Transcoding Service (FFmpeg): Handles video transcoding, segmentation, and thumbnail creation.
MongoDB: Stores metadata like video information, quality levels, and thumbnails.
File Storage: Stores processed video files and thumbnails locally.

Tech Stack

Node.js: Backend logic and API endpoints.
React: Frontend for user interaction.
Kafka: Manages distributed message queues for scalability.
FFmpeg: Performs video transcoding, segmentation, and thumbnail generation.
MongoDB: Stores metadata and provides quick access to processed data.
Docker: Ensures easy setup and consistent environments.
TailwindCSS: Enhances the frontend with modern styling.

Installation and Setup

Prerequisites

Install Docker.
Install Node.js (v16 or higher).
Clone the repository:

   git clone https://github.com/Ravikisha/RelaxTube.git
   cd RelaxTube

Steps

Run Docker Compose

   docker-compose up -d

Install Dependencies

   cd frontend && npm install
   cd ../backend && npm install
   cd ../transcoding-service && npm install

Start Services
- Backend:
```
 cd backend
 npm run dev
```

Frontend:
```
 cd frontend
 npm run dev
```
Transcoding Service:
```
 cd transcoding-service
 npm run dev
```

Access the Application Open your browser and navigate to http://localhost:3000.

Usage

Upload Videos: Users can upload videos through the frontend interface.
Processing: The backend processes the videos by:
- Transcoding them to multiple quality levels.
- Segmenting videos for HLS playback.
- Generating thumbnails.
Streaming: Processed videos are available for streaming via the frontend.
Batch Processing: Upload multiple videos for concurrent processing.

Screenshots

Homepage

Video Playback

Quality Selection

Upload Interface

Batch Upload

Scalability Features

Batch Processing: Process multiple videos simultaneously using Kafka.
Distributed Workers: Scale horizontally by adding workers for transcoding tasks.
Load Balancing: Distribute incoming requests across multiple backend servers.
Cloud Storage: Potential integration with AWS S3 or Google Cloud Storage for large-scale storage.
Monitoring: Use tools like Prometheus or Grafana for real-time monitoring and performance tracking.

Future Enhancements

Cloud deployment for global access and scalability.
Advanced analytics for tracking user interactions and video performance.
User authentication and access control.
Caching mechanisms for faster access to frequently requested content.

Contributing

We welcome contributions to RelaxTube! Feel free to submit pull requests, report issues, or suggest new features.

License

RelaxTube is licensed under the MIT License. See the LICENSE file for details.

Start exploring RelaxTube by visiting the GitHub Repository!

Building Scalable Web Applications with Microfrontends: A Detailed Walkthrough of Microfrontend Blog

Ravi Kishan — Sun, 29 Dec 2024 14:23:36 +0000

Introduction

In the rapidly evolving world of web development, creating scalable, maintainable, and modular applications is more important than ever. Enter microfrontend architecture—a game-changing approach that divides a monolithic frontend into smaller, independently deployable pieces.

This blog introduces Microfrontend Blog, a real-world implementation of microfrontends built using cutting-edge technologies like React, TailwindCSS, Clerk, Module Federation, and Firebase Firestore. Whether you're an experienced developer or just getting started with microfrontends, this project is a comprehensive guide to building modular web applications.

GitHub Repository: Microfrontend Blog

Project Overview

Microfrontend Blog is a blogging platform designed to demonstrate the power of microfrontend architecture. It splits the application into five key modules:

Auth Microfrontend: Handles user authentication using Clerk.
Dashboard Microfrontend: Allows users to create, edit, and manage blogs.
Viewer Microfrontend: Displays blogs with comment functionality.
Shared Components: A library of reusable components like headers, footers, and blog cards.
Container: Orchestrates the integration of all microfrontends.

By adopting Module Federation, each microfrontend is developed and deployed independently, enabling seamless collaboration across teams and simplifying the scaling process.

Features

Authentication: Secure login and signup with Clerk.
Blog Management: A rich dashboard for managing blogs.
Blog Viewing: Interactive blog display with a comments section.
Responsive UI: Styled with TailwindCSS for consistency across devices.
Scalability: Independent deployment of microfrontends.

Technologies Used

React: The foundation for building the UI.
TailwindCSS: A utility-first CSS framework for modern designs.
Clerk: A robust authentication library.
Firebase Firestore: Cloud-based database for blog storage.
Module Federation: Simplifies microfrontend integration.
Webpack: Efficient module bundler for development and production.

Architecture Diagram

The architecture demonstrates the interaction between microfrontends, the container, and backend services:

Getting Started

1. Prerequisites

Install Node.js (v16+).
Clone the repository:

  git clone https://github.com/Ravikisha/Microfrontend-Blog.git
  cd Microfrontend-Blog

2. Install Dependencies
For each microfrontend and shared components, run:

cd <microfrontend-folder>
npm install

3. Start the Development Server

npm start

4. Access the Application
Visit http://localhost:3005 to view the application.

Screenshots

Home Page:

Login Page:

Create Blog:

View Blog:

MicroFrontend Screenshots

Auth Microfrontend:

Dashboard Microfrontend:

Viewer Microfrontend:

Shared Components:

Container:

Key Benefits of Microfrontend Architecture

Independent Development: Teams can work on different microfrontends without stepping on each other's toes.
Scalability: Easily scale individual modules based on demand.
Reusability: Shared components streamline development and ensure design consistency.

Conclusion

The Microfrontend Blog project serves as a practical example of how microfrontend architecture can simplify development and improve scalability. With technologies like React, TailwindCSS, and Module Federation, developers can create robust and maintainable applications that meet modern web development demands.

Explore the code and start building your modular applications today!

GitHub Repository: Microfrontend Blog

Would you like me to add more details, such as common troubleshooting tips or deeper dives into individual microfrontends?

Introducing Stylesnap: Optimize Your CSS Like Never Before

Ravi Kishan — Sun, 29 Dec 2024 14:04:56 +0000

In the ever-evolving world of web development, efficiency and optimization are paramount. Meet Stylesnap, a cutting-edge solution for CSS optimization that simplifies your workflow and boosts performance. Designed for developers, this handy tool minimizes your CSS files by analyzing your project’s content and retaining only the styles you truly need.

What is Stylesnap?

Stylesnap is an NPX package tailored for modern web development. It scans your codebase—HTML, JSX, or any supported files—and generates a lightweight, optimized CSS file that eliminates unused styles. Whether you're using popular frameworks like Bootstrap, TailwindCSS, or custom CSS, Stylesnap has you covered.

Key Features

Selective CSS Extraction: Extracts only the required class names, tags, and selectors.
Framework Compatibility: Works seamlessly with CSS frameworks or custom styles.
Minification: Automatically minifies the generated CSS for improved performance.
Custom Configurations: Offers a customizable workflow using stylesnap.config.json.
Command-Line Simplicity: Easy-to-use CLI for quick integration.

Why Choose Stylesnap?

Enhanced Performance: Smaller CSS files mean faster page loads and better user experience.
Maintainability: Eliminates unused CSS, making your stylesheets cleaner and easier to manage.
Flexibility: Compatible with various frameworks and custom setups.
Developer-Friendly: Simple installation, intuitive CLI options, and detailed documentation.

Getting Started

Installation

Use npm to install Stylesnap as a development dependency:

npm install stylesnap --save-dev

Or run it directly with NPX:

npx stylesnap

Usage

Stylesnap’s CLI makes it easy to optimize your CSS. Here’s a quick example:

Initialize Configuration:

   npx stylesnap --init

This creates a stylesnap.config.json file in your project.

Update Configuration: Edit the file to suit your project’s needs:

   {
     "content": ["./src/**/*.html", "./src/**/*.jsx"],
     "css": "./src/styles.css",
     "output": "./dist/optimized.css",
     "minify": true
   }

Run Stylesnap:

   npx stylesnap

Your optimized CSS will be saved at the specified output location.

Real-World Benefits

By using Stylesnap, you’ll see immediate improvements in your development and deployment process:

Faster Load Times: Reduced CSS file size enhances website speed.
Smaller Builds: Ideal for production environments.
Streamlined Debugging: With unused CSS eliminated, debugging becomes simpler.

Contribute

Stylesnap is open-source, and contributions are welcome! If you encounter any issues or have ideas for improvement, feel free to open an issue or submit a pull request.

Start optimizing your CSS today with Stylesnap! 🚀 Streamline your workflow, boost performance, and take your web development projects to the next level.

A Comprehensive Guide to Building a Single Sign-On (SSO) Gateway with Node.js

Ravi Kishan — Sun, 22 Dec 2024 17:13:18 +0000

Single Sign-On (SSO) systems have become critical in today's interconnected application ecosystems. By allowing users to log in once and access multiple applications seamlessly, SSO simplifies authentication, enhances user experience, and bolsters security. This blog dives into the implementation of an SSO Gateway using Node.js, Express, and MongoDB, guiding you through its features, architecture, setup, and best practices.

What is a Single Sign-On Gateway?

An SSO Gateway is a centralized authentication system where users authenticate once and gain access to multiple interconnected applications without needing to reauthenticate. The Node-SSO-Gateway project demonstrates a robust yet simple implementation of such a system.

Key Features of the Node-SSO-Gateway

Centralized Authentication
- Users log in via a single SSO server, eliminating the need for multiple logins.
Token-Based Authorization
- Secure, stateless communication between the SSO server and consumer applications via JSON Web Tokens (JWT).
Cross-Domain Session Management
- Maintain seamless user sessions across multiple applications and domains.
MongoDB Integration
- Secure storage of user credentials with robust password hashing (e.g., bcrypt).
Dynamic Consumer App Registration
- Consumer applications can dynamically register themselves with the SSO server for authentication.
Logout Functionality
- Supports global and local session termination for enhanced security.

System Architecture

The system is divided into three primary components:

SSO Server

The central hub that authenticates users, manages sessions, and issues JWT tokens.
Consumer Applications (Clients)

Applications relying on the SSO server for authentication. Each client establishes a local session after verifying the token.
MongoDB

A database backend to securely store user data, including email and hashed passwords.

Architecture Diagram

How Does It Work?

User Login
- Users log in through the SSO server. Upon successful authentication, the server issues a JWT token and redirects the user to the desired consumer app.
Token Validation
- Consumer apps verify the JWT token with the SSO server before granting access to protected resources.
Session Management
- Both global (SSO server) and local (consumer app) sessions are managed, ensuring secure and consistent access.
Logout
- Users can log out from the SSO server, terminating the global session, or from a consumer app, terminating the local session.

Setting Up the Node-SSO-Gateway

1. Prerequisites

Node.js and npm installed.
MongoDB instance running (local or cloud-based).
Basic knowledge of JWT, Express, and MongoDB.

2. Clone the Repository

git clone https://github.com/Ravikisha/Node-SSO-Gateway.git
cd Node-SSO-Gateway

3. Install Dependencies

Navigate to the root directory of each component and install the required packages.

For the SSO Server

cd server
npm install

For Consumer Applications

cd client1
npm install

# In another terminal
cd client2
npm install

4. Configure MongoDB

Create a .env file in both the SSO Server and consumer apps with the following content:

MONGODB_URI=mongodb://localhost:27017/sso-db

5. Start the Applications

Start the SSO Server:

cd server
npm run dev

Start the consumer apps:

cd client1
npm run dev

# In another terminal
cd client2
npm run dev

6. Test the System

Visit http://localhost:3000 to access the SSO server login page.
Successfully log in to be redirected to consumer apps (http://localhost:3001 and http://localhost:3002).

Adding New Consumer Applications

Create a new app following the structure of client1.
Register the app’s domain in the SSO Server’s allowedOrigin configuration.

   const allowedOrigin = {
       "http://localhost:3001": true,
       "http://localhost:3002": true,
       "http://localhost:3003": true,
   };

Redirect authentication requests to the SSO Server.

Security Best Practices

HTTPS Everywhere
- Use HTTPS in production to ensure encrypted communication.
Secure JWT Storage
- Store JWT securely, preferably in HTTP-only cookies, to prevent XSS attacks.
Validate Origins
- Validate consumer app origins to prevent unauthorized requests.
Password Hashing
- Use strong hashing algorithms like bcrypt for storing user passwords.

Logout Functionality

Local Logout
- Removes the session from the consumer app only.
Global Logout
- Terminates the session on the SSO Server, logging the user out from all consumer apps.

Screenshots

Login Page

SSO Server Page

Consumer Application (Client1)

Consumer Application (Client2)

Conclusion

The Node-SSO-Gateway project offers a secure and scalable solution for centralized authentication across multiple applications. By leveraging modern web technologies like Node.js, Express, and JWT, the system ensures a seamless user experience and robust security. Whether you're building a microservices-based architecture or integrating multiple platforms, this SSO solution is a solid foundation for managing authentication effectively.

Explore the repository here and get started with centralized authentication today!

DEV Community: Ravi Kishan

GUML: Let the Model Write 24 Lines and the Compiler Write the Other 229

Table of Contents

Why I built this

The 24-line argument

A tour of the language

Inside the compiler

A lexer that cannot decide alone

Every error in one pass

Diagnostic codes are an API

Did you mean card?

Repair without a model

What 24 lines become

Seven backends, one vocabulary

Themes and capabilities

A theme is data, with a contract

What will this document do?

What is measured, and what is not

Measured: authored fixtures, a real tokenizer

The content floor

Measured: GUML against its own compiler output

Measured: the cost of a change

Not measured

A real model tried it

The playground and the chat

Proof: what I ran for this post

What I found while writing this

1. "Apply 3 fixes" deletes a line

2. Web Components: Delete changes the filter

3. Svelte: new tasks are posted empty

4. raw html passes the "inert" gate

5. Docs drift

The question still open

What I learned

What's next

Try it

10 Algorithm Patterns That Crack Most Coding Problems, Visualized

Table of Contents

Why patterns beat memorising problems

Which pattern? A cheat sheet

Pattern 1: Two pointers

Sample problem: Two Sum II (LeetCode 167)

Pattern 2: Sliding window

Sample problem: Longest Substring Without Repeating Characters (LeetCode 3)

Pattern 3: Fast and slow pointers

Sample problem: Linked List Cycle II (LeetCode 142)

Pattern 4: Prefix sum and hash map

Sample problem: Subarray Sum Equals K (LeetCode 560)

Pattern 5: Binary search on the answer

Sample problem: Koko Eating Bananas (LeetCode 875)

Pattern 6: Monotonic stack

Sample problem: Daily Temperatures (LeetCode 739)

Pattern 7: BFS by levels

Sample problem: Rotting Oranges (LeetCode 994)

Pattern 8: Backtracking

Sample problem: Subsets (LeetCode 78)

Pattern 9: Top K with a heap

Sample problem: Kth Largest Element in an Array (LeetCode 215)

Pattern 10: Dynamic programming

Sample problem: Coin Change (LeetCode 322)

Complexity at a glance

Honourable mentions

How to practise

RustDNS: Writing a Recursive DNS Resolver in Rust, Byte by Byte

Table of Contents

Why I built this

DNS in two minutes

Hello, resolver

The map of the code

A 512-byte cursor

Twelve bytes of header

A real packet, byte by byte

Names, labels and compression pointers

One enum per record type

Writing: backpatching the length

Walking the tree: recursive resolution

Serving dig on port 2053

Breaking it on purpose

Bug 1: the MX query that never came back

Bug 2: an NXDOMAIN that lies about itself

4. `raw html` passes the "inert" gate

What `loadNative()` actually does

Annotations: `@sync`, `@async`, `@cost`

What happens when you run `relaxicons add`

Container Lifecycle (`startContainer`, `child`)