plugins

BareProxy Link Previews Plugin: Open Graph Cards for Pages That Don't Have Them

Status: built, number 9 of 21 in BareProxy’s build order, and out in BareProxy 0.11.0 as previews.wasm on the releases page. Its manual is the README in the code repository.

Paste a link into Slack, WhatsApp, LinkedIn, X or iMessage, and a fetcher comes to read the page’s Open Graph tags: a title, a description and an image for the preview card. A page without them shows up as a bare URL, or with whatever text the fetcher grabbed first, often a cookie notice. Plenty of pages lack them: old pages, app screens, documentation, files a CMS never touched.

What It Does

  • Fills in what’s missing. When a preview fetcher asks for an HTML page without Open Graph tags, the plugin adds them to the page’s <head>: the page’s title, its meta description or first real paragraph as the description, and its first proper picture, or a default image from the config.
  • Leaves good pages alone. Only the tags a page lacks are added, and a page with all of them passes through untouched.
  • Only for fetchers. Twenty preview fetchers are recognized by user agent, from Slack and WhatsApp to Mastodon and Bluesky, and visitors’ pages are never changed. The tags describe the same page a visitor sees, so a preview never promises something the page doesn’t have.
  • Rules per path. A section can get a fixed card from the plugin’s config, such as one title, description and image for all of /docs/.

Here is a config:

plugin previews /etc/bareproxy/plugins/previews.wasm
  config /etc/bareproxy/plugins/previews.conf
  body response

site example.com
  use previews
  route /* -> files /var/www/example/public

And the plugin’s own, which can be empty:

# previews.conf
site-name Example
image /img/card.png

Costs Visitors Nothing

A plugin that rewrites pages normally has every page held back for it, which slows down every visitor. This one tells BareProxy, request by request, that it only wants the page when a fetcher is asking. 0.11.0 added that ability to BareProxy itself. Everyone else’s pages stream past the plugin as if it weren’t there, and files still go out the fast way.

Where It Fits

Link previews and RenderCache solve neighboring problems. RenderCache gives a fetcher a whole rendered page when the page is built by JavaScript. Link previews make sure a plain HTML page tells the fetcher what it is. A JavaScript app may want both; a static site needs only this one.

Each page it changes carries a note in the request’s record, with the tags it added and the fetcher it added them for.

The whole program is on the plugins page.