Skip to content

[RFC] Commit embeds #1521

Open
Open

Description

@jubianchi

Summary

Let people show a /dev/null commit on their own site (a blog, docs, a Notion page) as a card that looks and reads like /dev/null: the commit, optionally the rest of its author's thread, and its replies, down to several levels. The card is an iframe served by /dev/null, so it always shows the commit's current state. An oEmbed endpoint lets blogging platforms build the card from a link.

A /dev/null thread embedded in a blog post

Motivation

Quoting a thread in a blog post, a newsletter or docs today means taking a screenshot. A screenshot loses the links, the code, the polls and the conversation, and it stays up after the author deletes the commit. A card served by /dev/null stays live, leaves the author in control, and sends readers back to the thread.

Goals and non-goals

Goals:

  • Embed a single commit, a thread, or replies to replies, as chosen by whoever creates the embed.
  • Render everything a commit can hold the way /dev/null does: formatting, code, emoji, mentions, hashtags, links, quoted commits, color swatches, images, link cards, players and polls. Draw it on the same graph rail.
  • Respect deletion, moderation and the author's choice on every page that shows the card.

Non-goals:

  • Interacting from the card. Starring, voting, replying and translating stay on /dev/null.
  • Measuring embeds. There are no view counts, no referrers and no tracking.
  • Embedding anything other than commits, such as profiles, logs or Remotes.

Product

Who can embed what

  • Only signed-in members can create an embed, for any approved, public commit. Readers of the page that shows it don't need an account.
  • This is enforced, not just hidden: every embed URL is signed by /dev/null (see Signed URLs), so a guest can't build one by hand.
  • Embeds are on by default. Authors can turn them off in Settings → Profile. For commits posted as an organization, the organization's setting applies, and only its admins can change it.
  • Turning embeds off also affects cards that already exist, since the card is served live: they then read [unavailable].
User Organization
Settings → Profile: the Embeds section with its switch An organization's settings: the same Embeds section, for admins

Entry point

Embed commit sits in the commit's "…" menu, right after Send in Remotes. Guests don't see it. It is also hidden when the commit can't be embedded: when it isn't approved, when it is deleted, or when its author or organization turned embeds off.

A commit's menu: Copy link, Send in Remotes, then Embed commit

The dialog

It is a regular /dev/null dialog, widened to fit a live preview of the card. The preview sits next to the settings, or under them on phones. The settings follow the conventions of the Settings pages:

Setting Control Default Shown when
The rest of the thread Switch On The commit starts a self-thread
Replies Switch On The commit has replies
Per level 1, 3, 5, 10 3 Replies is on
Levels 1, 2, 3, All 3 Replies is on
Max height 480px, 640px, 800px, None 640px Always
Theme Light, Dark, Auto Auto Always

On a reply, a note replaces the thread switch: the card always starts from the root commit.

The footer has three tabs. Each one shows its code in the same CodeBlock as commits:

  • HTML: the iframe and the resize script, for any site that accepts HTML.
  • Markdown: the commit's preview image linked to the commit. Markdown renderers, like GitHub READMEs, strip frames, so this is the best they can show.
  • Link: the commit link, with the settings and their signature as parameters, for sites that support oEmbed.

Copying prints a toast in the voice of the commit toast, [embed 9f3c2a1] copied. A failed copy prints fatal: could not copy embed code for 9f3c2a1.

The Embed commit dialog: settings on the left, the live card on the right, the code below

What the card shows

The card reads like the commit's page and is drawn with the same components.

  • A top-level commit: the commit, then the rest of its self-thread when enabled (1/3, 2/3…), then its replies.
  • A reply: the whole chain from the root commit down to the reply, then the reply's own replies.
  • Replies: the first N direct replies at each level, down to the chosen depth.
    • When a level holds more replies than the card shows, it ends with Show the last N, like on /dev/null.
    • Replies below the last level show up as › N replies in the actions row.
    • Both link to the commit on /dev/null.
  • Each commit: the same header as on /dev/null (name, handle, date, thread badge, and the hash on the right), the same body, and the commit it quotes. Dates are absolute (Nov 6), because relative times age badly in an article.
  • The embedded commit is drawn like the focused commit on its page, with a larger body and the full date line.
  • Actions: /dev/null's actions row, read-only. The star count and › N replies open the commit on /dev/null.
  • Polls: while a poll is open, its options link to /dev/null to vote, and no results are shown. Once it is closed, the card shows the final results.
  • Text: always in its original language, with no Translate control.
  • Players: they work like on /dev/null, and load only once the reader presses play.
  • Footer: the /dev/null logo and View on /dev/null →.
  • Max height: past it, the thread scrolls inside the card, and the footer stays in view.
A reply, from the root A single commit A narrow page
An embedded reply: its ancestors from the root, then its own replies A single commit The card on a phone-width page

Tombstones

A commit that can't be shown keeps its place in the card, without author or body, so the rest of the thread still reads. This applies to the embedded commit itself too.

Tombstone When
[deleted] The commit was deleted
[unavailable] The commit is pending or rejected, or its author or organization turned embeds off

Opting out reads [unavailable] on purpose: a card shouldn't tell the world who turned embeds off.

An embedded commit that is still pending, shown as [unavailable]

The card always renders what a guest sees on /dev/null. There is no session, so there are no mutes or blocks to apply.

Naming

I went with embed, both in the UI (Embed commit) and in code (/embed, allows_embeds). PRODUCT.md stops the git metaphor at commit and log outside Remotes, and asks for labels anyone understands. The git voice lives in the copy instead, as in the [embed 9f3c2a1] copied toast.

Cherry-pick would be the git-flavored alternative, as in Cherry-pick commit, /cherry-pick/{commit} and allows_cherry_picks. It has three problems:

  • PRODUCT.md would need a second exception, next to the one for Remotes.
  • It says less than "embed" to someone who doesn't use git.
  • In git, a cherry-pick is a copy that no longer follows its source. A card does follow its source, so the word promises the opposite of what the feature guarantees.

Technical design

Overview

sequenceDiagram
    autonumber
    participant Author as Embed author
    participant App as dev-null.sh
    participant Site as Third-party page
    participant Reader as Reader's browser

    Author->>App: "…" → Embed commit, pick settings
    App-->>Author: Signed iframe + embed.js, or signed commit link
    Author->>Site: Paste code or link
    alt Link on an oEmbed consumer
        Site->>App: GET /oembed?url=…
        App-->>Site: rich oEmbed JSON with the iframe
    end
    Reader->>Site: Open the page
    Reader->>App: GET /embed/{uuid}?…&signature=…
    App-->>Reader: Server-rendered card, framable, no cookies
    Reader->>Reader: Card posts its height, embed.js sizes the iframe
Loading

Routes

Method Path Purpose
GET /embed/{commit} The card: signed, framable, sessionless
GET /embed.js The resize script, static and long-cached
GET /oembed The oEmbed provider, JSON only
GET /commits/{commit}/embed-link Members only: signs the card's URL and returns the HTML, Markdown and Link code
PUT /settings/embeds The user's setting
PUT /organizations/{organization}/settings/embeds The organization's setting, admins only

When the commit page is opened from a signed embed link, it gets an oEmbed discovery <link> in its <head>.

Parameters

/embed/{commit} and the Link tab's commit URL share the same parameters:

Parameter Values Default
thread 1 Off
replies 1, 3, 5, 10 Off
depth 1, 2, 3, all 3 with replies
theme light, dark Auto
max_height 480, 640, 800, none 640

Unknown or out-of-range values fall back to their default. The commit is always addressed by its UUID, never by its short hash.

Signed URLs

Every embed URL carries a signature: an HMAC of the path and the normalized query, keyed with the application key. This uses Laravel's relative signed routes, URL::signedRoute(absolute: false) and signed:relative, without expiry.

  • Only the dialog's endpoint, which needs a signed-in member, produces signatures. Without a valid signature, /embed answers 403 and /oembed answers 401, so consumers fall back to a plain link.
  • A bare commit link pasted into an oEmbed consumer therefore gives no card. Only the Link tab's signed link does.
  • The signature covers the commit and the settings, and nothing else. Nothing is stored, and nothing ties an embed to the member who created it.
  • Because the settings are signed, nobody can derive other cards from an existing one. That also rules out cache-busting variants.
  • The signature leaves out the scheme and host, so cards keep working behind a proxy that terminates TLS, or on another domain of the app. With absolute signatures, every card answered 403 through a tunnel.
  • Rotating the application key invalidates every existing embed. That is acceptable for a key rotation, but worth a line in the runbook.

The embed page

  • Middleware: it runs outside the session and CSRF handling of the web group, so it sets no cookie and always renders the guest view.

  • Framing: it is the only page excluded from PreventFraming. It sends Content-Security-Policy: frame-ancestors * and no X-Frame-Options.

  • Query: it builds the tree once from the embedded commit, made of the ancestors up to the root, the self-thread, and N replies per level down to the depth. Each node is marked visible, or with its tombstone. Visibility follows the guest rules (approved, not deleted) plus the embed setting of the author or organization.

  • Bundle: the card has its own client entry point, resources/js/embed.tsx. It loads the card's page only, without the app's live updates, analytics or service worker. On the server, the card renders through the app's SSR bundle.

  • Rendering: an Inertia page with a bare layout, built from the commit page's components:

    • CommitHeader, GraphRail, ReplyBranch, CommitBody, QuotedCommit;
    • CommitPoll, LinkPreview, TombstoneLine.

    Read-only props turn off every control that writes. Links in the body are plain links, so hovering a mention fetches nothing from /dev/null.

Without JavaScript

Two scripts are involved, and a card missing either one still reads:

Missing When What the reader gets
embed.js, on the host page The site strips <script> but keeps frames (many CMSs) The card at the height written in the code: max_height plus the footer, 685px by default
The card's own JS JavaScript is off, or the frame is sandboxed without allow-scripts The whole card as rendered by the server: text, highlighted code, images, links, the rail, tombstones
  • Links open outside the frame through <base target="_blank">.
  • Only a few things need JavaScript: the copy and Wrap lines controls of code blocks, the players, and the height message.
  • An explicit Light or Dark theme holds without JavaScript. Auto stays light, since only the browser knows the reader's preference.
  • A site that strips <iframe> as well gets nothing from the HTML tab. The Markdown tab and oEmbed exist for that case.

The card with JavaScript turned off, rendered by the server

Resize protocol

The card posts its height to the host page whenever it changes:

parent.postMessage({ type: 'devnull:embed:resize', id, height }, '*')

embed.js only accepts this message from the origin it was loaded from. It resizes the one frame that sent it, and listens only once even when a page includes it several times. With a max height, the card caps itself and scrolls inside, so the frame never grows past max_height plus the footer.

oEmbed

GET /oembed?url=…&maxwidth=…&format=json returns a rich response whose html holds the iframe and the script:

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "/dev/null",
  "author_name": "Mira Okafor",
  "html": "<iframe src=\"https://dev-null.sh/embed/…\" …></iframe><script async src=\"https://dev-null.sh/embed.js\"></script>",
  "width": 550,
  "height": 685,
  "cache_age": 3600
}
  • The embed parameters on url carry over to the iframe. The width follows maxwidth, up to 550px.
  • The endpoint answers 404 for an unknown commit. It answers 401 when the link isn't signed or the commit can't be embedded, and 501 for format=xml.
  • For an organization's commit, author_name is the organization's name. The member who posted it is never revealed.
  • Platforms with an allowlist, such as WordPress core, need /dev/null registered with them. The oEmbed providers registry is the first step.

The card in a Notion page, built from the Link tab's signed link

Data

Table Column Default Who sees it Deleted
users allows_embeds true The user With the account
organizations allows_embeds true The org's admins With the organization

The column is included in the export. Nothing else is stored: no embed records, no referrers, no counters.

Load and abuse

Every reader of an article loads the card anonymously. That makes /embed and /oembed the cheapest way to make /dev/null work without an account, so they have to cost an attacker more than they cost the server.

  • Rate limits, next to the existing limiters:
    • embeds allows 120 requests per minute per IP and commit, so a page with several cards still loads, and 600 per minute per IP, so one address can't walk every commit.
    • oembed allows 60 requests per minute per IP, since consumers fetch a link once and cache the result.
  • Bounded work:
    • The signature is checked before any query, so a forged URL costs one HMAC.
    • Parameters are a closed set, so a commit has a few dozen possible cards at most.
    • A card holds at most 40 commits, whatever depth is asked for. depth=all never walks an unbounded thread.
    • The route constraint rejects a malformed UUID before any query.
  • No writes: serving a card never writes to the database or the session.
  • Static script: embed.js is a static file with a long cache.

Planned, but not built yet in #1522:

  • A 30-second cache of the rendered tree, per commit and settings. It would be forgotten as soon as a commit in the thread is deleted or moderated, or its author changes their setting, so a card is never staler than /dev/null.
  • A readable fallback with a link to the commit when a card is throttled (429), instead of Laravel's error page.
  • A constant number of queries to build the tree, whatever its size. feat: let members embed commits on other sites #1522 queries each node's replies.

Security and privacy

  • The card is the only framable page. Everything else keeps PreventFraming.
  • The card sets no cookie, so there is no session to ride on, no clickjacking of signed-in actions, and nothing written from the card.
  • The resize message only carries a height, and embed.js checks its origin before acting on it.
  • The card shows only what a guest sees. Pending, rejected and opted-out content never leaves /dev/null, and an organization's commit never reveals who posted it.
  • Third-party players load only after the reader presses play, as they do today.

Rollout

#1522 implements everything in one draft, so the design can be tried out. It can be split into separate pull requests:

  1. The setting: migration, the user and organization settings, the export.
  2. The card: the route, middleware and tree query, and the read-only page.
  3. embed.js: the resize script.
  4. oEmbed: the endpoint and the discovery link.
  5. The dialog: the menu entry, the signing endpoint, the dialog.
  6. Docs: KNOWLEDGE_BASE.md, DESIGN.md (a Commit Embed component, and an exception to the No Cards Rule) and PRODUCT.md.

Open questions

  • The name: embed or cherry-pick (see Naming).
  • The rollout: should this ship as one PR, or split as above?
  • The edge: do /embed and /oembed deserve a dedicated rule in front of the app?

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions