DEV Community: Dave Cross

Choosing the Right Database Abstraction

Dave Cross — Sun, 28 Jun 2026 09:24:43 +0000

A question came up recently in the Perl community asking whether, in a Mojolicious application, it’s better to use DBIx::Class or a Mojolicious-specific module like Mojo::Pg.

It’s an interesting question, but I think it’s asking the wrong thing.

I’ve spent almost forty years moving up the stack of database abstractions. Every few years, someone invents a new layer, and every few years, experienced programmers explain that they don’t need it because they’re perfectly capable of working at the layer below. I’ve watched exactly the same argument play out over CGI, web frameworks, ORMs, containers and now AI-assisted coding.

Sometimes the new abstraction turns out to be a dead end. More often, it’s simply another step that lets us spend less time on plumbing and more time solving the problems our users actually care about.

I think that’s what’s really going on here.

You’re comparing different layers

The first thing that struck me about the discussion was that it jumped straight from DBIx::Class to Mojo::Pg, as though they were equivalent choices. I don’t think they are.

If you zoom out a little, there are several layers involved in database access:

Application
DBIx::Class / DBIO (ORM)
DBI
DBD::Pg / DBD::SQLite / DBD::MariaDB
Database

Each layer builds on the one below it. DBIx::Class sits on top of DBI, DBI sits on top of a database driver, and the driver talks to the database itself. Every layer gives you a slightly richer abstraction whilst hiding a little more of the mechanics.

Mojo::Pg occupies a rather different place. It’s a PostgreSQL library designed specifically for Mojolicious. That’s a perfectly sensible design if you’ve already decided you’re using both PostgreSQL and Mojolicious, but it couples together decisions that I’d normally prefer to keep separate.

Personally, I like choosing my web framework independently of my database, and my database independently of my data access layer. The more independent those decisions are, the easier it is to change one without affecting the others.

Why I moved up the stack

I started writing embedded SQL in C in the late 1980s. When I moved to Perl in 1996, I used Sybperl, which was a thin layer over the proprietary Sybase database API. When I discovered DBI, I adopted it enthusiastically because it removed an enormous amount of repetitive code whilst remaining database-independent. Later, when DBIx::Class became mature enough for production systems, I happily moved another level up the stack.

None of those decisions happened because I couldn’t write SQL. I’ve been writing SQL since 1988 and I’m perfectly happy doing so.

The point was that I no longer wanted to spend my time writing the same joins, the same foreign key lookups and the same bits of boilerplate over and over again. Those aren’t the interesting parts of my applications. They’re necessary, but they’re plumbing. Good abstractions let me write that plumbing once and then think about the domain I’m modelling instead.

This isn’t just about databases

A few weeks ago, I wrote about The Long Road from CGI to Containers. The point of that article was that the history of web development is largely the history of building better abstractions.

We moved from CGI scripts to web frameworks. From hand-written deployment procedures to containers. Every step let us express our intent at a higher level whilst worrying less about the implementation details.

Database programming has followed exactly the same path.

But I like writing SQL

Whenever I recommend an ORM, someone inevitably assumes it’s because I don’t know SQL.

Nothing could be further from the truth.

SQL is probably the programming language I’ve been writing the longest. I enjoy writing SQL. But I don’t enjoy writing the same SQL repeatedly.

I don’t want every controller containing another join between the same tables. I don’t want to duplicate the same WHERE clause in half a dozen places. I don’t want to remember every foreign key relationship every time I touch the code.

Those things aren’t business logic; they’re plumbing.

An ORM lets me move that plumbing into one place and give it names.

What DBIx::Class gives me

For me, the biggest advantage of DBIx::Class isn’t that it generates SQL.

It’s that it models my application.

A Person has many Titles.
A Title belongs to a Person.
A User> has many Orders.

Those relationships become part of the vocabulary of the application. Queries become reusable methods. Business rules become object methods instead of comments beside SQL statements.

Instead of thinking about joins, I’m thinking about people, titles and orders.

That’s a much nicer level of abstraction.

Isn’t it slower?

One criticism often levelled at DBIx::Class is performance.

That’s not entirely unfair. It’s perfectly possible to write inefficient DBIx::Class code. I know because I’ve done it.

While recently carrying out some optimisation on my Line of Succession application, I discovered one page was generating hundreds of unnecessary database queries. The solution wasn’t to abandon DBIx::Class and replace it with hand-written SQL. The solution was to understand the ORM better.

Adding a couple of well-placed prefetch clauses reduced the number of queries dramatically with almost no change to the surrounding code.

The ORM wasn’t the problem; my use of the ORM was.

That’s a useful lesson. Every abstraction has a learning curve. If you don’t understand how it’s working underneath, you’ll eventually hit performance problems. But once you do understand it, you can often achieve dramatic improvements without sacrificing the higher-level API that made you choose the abstraction in the first place.

What if I just want to write SQL?

One thing that struck me about the original discussion is that it jumped straight from DBIx::Class to Mojo::Pg, as though those were the only two choices.

I don’t think they are.

If all I wanted was to execute SQL from a Mojolicious application, I’d probably start by looking for a DBI-based solution rather than one that’s tied specifically to PostgreSQL. Something like Mojolicious::Plugin::Database seems like a more natural fit, as it lets me use the standard Perl database abstraction whilst integrating cleanly with Mojolicious.

That still leaves me free to choose PostgreSQL, SQLite, MariaDB or whatever other database makes sense for the project.

By contrast, choosing Mojo::Pg bakes the decision to use PostgreSQL into your application at a deeper level than I’d be comfortable with.

Good abstractions should reduce coupling, not increase it.

The model layer

Of course, in larger applications, there’s usually another abstraction on top of the ORM itself. My controllers don’t generally talk directly to DBIx::Class resultsets; they ask domain-level questions such as “Who was sovereign on this date?” The fact that the answer currently comes from DBIx::Class is an implementation detail. That’s another useful abstraction—but it’s probably a topic for another article.

Aside: What happened to DBIx::Class?

For a long time, this was the awkward question.

Around a decade ago, active development effectively stopped. This wasn’t because the technology had failed or because the community lost interest. The maintainer had explicitly stopped development, and measures such as the CPAN NOXFER co-maintainer flag prevented the normal open source succession process from happening.

For years, that left DBIx::Class in an uncomfortable position. It remained stable and widely used, but there was understandable uncertainty about its long-term future.

Fortunately, that situation finally appears to be changing. DBIO appeared on CPAN just a few days ago. It has taken the hard-fork route, preserving the ideas that made DBIx::Class successful whilst allowing active development to resume.

Whether DBIO ultimately becomes the successor to DBIx::Class isn’t really the important point.

The important point is that these ideas are still valuable enough that people are prepared to invest significant effort in carrying them forward.

Choosing your abstraction

I don’t think this is fundamentally a question about Mojolicious.

I’d happily use DBIx::Class with Mojolicious, Dancer2 or any other web framework. I’d happily use DBI with all of them too. The web framework and the data access layer are largely independent architectural decisions, and I generally prefer to keep them that way.

The important decision isn’t the framework.

It isn’t even the database.

It’s deciding where you want your application to live.

Do you want to think in terms of SQL?

Do you want to think in terms of tables?

Or do you want to think in terms of the concepts that make up your application’s domain?

After nearly forty years of writing SQL, I know which one I’d rather spend my day thinking about.

The best abstraction isn’t the one that hides the most detail.

It’s the one that lets you spend most of your time thinking about the problem you’re actually trying to solve.

Public Identifiers, UUIDs and a Tiny SEO Fix

Dave Cross — Sat, 06 Jun 2026 14:29:38 +0000

A recent question from my friend and colleague Mohammad got me thinking about the way we identify data in web applications.

While working on the DBIC component of a REST API, he came across the term enumeration attack. In this type of attack, an attacker systematically guesses resource identifiers in order to access data they shouldn’t be able to see.

For example, if your API exposes URLs like this:

GET /users/123
GET /users/124
GET /users/125

then it’s easy for someone to try a large range of identifiers and see what they get back.

Mohammad’s question was simple:

Should we replace sequential IDs with UUIDs? And if we do, should we index the UUID column?

As is often the case, the answer turned out to be “it depends”.

Two Different Types of Data

The first thing I realised is that not all data objects have the same requirements.

Some objects are naturally public.

For example, books on a publishing website are intended to be discovered. In fact, you probably want people to be able to guess their URLs:

/books/design-patterns-in-modern-perl

In this case, a human-readable slug makes perfect sense.Other objects are private by nature. User accounts, orders, invoices and API resources generally shouldn’t be enumerable. In those cases, a UUID is often a better choice:

/users/550e8400-e29b-41d4-a716-446655440000

The important observation is that slugs and UUIDs solve different problems.

Slugs are for humans (and, perhaps, search engines).
UUIDs are for machines.

Database Design

A common question is whether a UUID should replace the primary key.

In most cases, I don’t think it should.

My preferred design is:

CREATE TABLE users (
  id BIGINT PRIMARY KEY,
  uuid UUID NOT NULL UNIQUE
);

The integer primary key remains the internal identifier used for joins and foreign keys.

The UUID becomes the public identifier exposed through APIs.

This gives you the best of both worlds:

Small, efficient foreign keys.
Fast joins.
Unguessable public identifiers.

If the application regularly searches by UUID then the UUID column should be indexed. In practice, declaring it UNIQUE will usually create the appropriate index automatically.

The Hybrid Approach

Thinking about this reminded me that many large sites use a hybrid approach.

Amazon product URLs contain both a human-readable title and a stable identifier:

/Design-Patterns-Modern-Perl/dp/B0XXXXX123

The ASIN is what really identifies the product.

The title is there for humans.

Stack Overflow does something similar:

/questions/12345/how-do-i-index-a-uuid-column

Again, the question ID is authoritative. The title is helpful context.

My Line of Succession website uses the same idea.

A person page looks like this:

/p/2b5998-the-prince-william-prince-of-wales

The important part is the identifier:

2b5998

The rest is descriptive text.

This turns out to be particularly useful for royalty because titles change constantly. Someone might be “Prince William”, then “The Prince of Wales”, and eventually “King William V”.

By separating identity from presentation, old links continue to work regardless of title changes.

A Tiny Bug

While thinking about all of this, I discovered a small bug in Line of Succession.

The site allows any descriptive text after the identifier. These URLs all resolve to the same person:

/p/2b5998-the-prince-william-prince-of-wales
/p/2b5998-prince-billy
/p/2b5998-fred

The application correctly ignores the descriptive text and uses only the identifier.

However, there was a problem.

The page was generating its canonical URL from the incoming request path rather than from the person record.

That meant a request for:

/p/2b5998-prince-billy

generated:

<link rel="canonical"
      href="https://lineofsuccession.co.uk/p/2b5998-prince-billy">

which is obviously not the canonical URL.

The fix was surprisingly small:

sub canonical( $self ) {
   if ($self->request->is_date_page) {
     return '/' . $self->canonical_date;
+ } elsif($self->request->is_person_page) {
+ return '/p/' . $self->request->person->slug;
   } else {
     return $self->request->path;
   }
 }

At the same time I simplified another method by making it reuse the canonical URL logic.

The result was a six-line patch that fixed the SEO issue and made the code slightly cleaner.

Those are my favourite kinds of fixes.

Future Improvements

The fix also revealed an emerging abstraction in the code.

At the moment, various parts of the application know how to construct URLs for different object types.

A cleaner approach would be to give objects responsibility for generating their own URLs.

I’m considering a HasURL role that would require an object to provide an identifier and optionally a prefix, and then build the URL automatically.

That’s a job for another day.

For now, a small question about UUIDs led to a useful discussion about public identifiers, a review of URL design, and a tiny production fix. Not bad for an afternoon’s work.

The post Public Identifiers, UUIDs and a Tiny SEO Fix first appeared on Perl Hacks.

Teaching AI About the British Monarchy with MCP

Dave Cross — Sat, 30 May 2026 09:58:02 +0000

One of the more interesting additions I’ve made recently to the Line of Succession website is support for the Model Context Protocol (MCP).

If you’ve spent any time around AI tooling recently, you’ve probably seen people talking about MCP. It’s often described as “USB for AI”, which is perhaps a little overblown, but the basic idea is sound. MCP provides a standard way for AI assistants to discover and use external tools and data sources.

In practical terms, it means that instead of building bespoke integrations for ChatGPT, Claude, Gemini and whatever comes next, you expose a standard MCP endpoint and let the AI clients do the rest.

For a data-driven site like Line of Succession, that seemed like an obvious experiment.

What is MCP?

The Model Context Protocol was originally developed by Anthropic and has rapidly become one of the emerging standards in the AI ecosystem.

An MCP server exposes:

Information about itself
A list of available tools
Schemas describing how those tools should be called
The results returned by those tools

An AI client can connect to the server, discover the available tools and invoke them when needed.

Instead of scraping web pages or attempting to infer information from HTML, the AI gets access to structured data.

That’s exactly the kind of thing Line of Succession is good at.

Why Add MCP?

The site already exposes information through a traditional web interface and a JSON API.

But those interfaces were designed for humans and developers respectively.

MCP gives AI systems a much cleaner integration point.

For example, an AI assistant can now answer questions like:

Who was the British sovereign on 14 November 1948?
What did the line of succession look like in 1980?
Who was next in line when Queen Victoria died?

without having to scrape pages or understand the site’s internal URLs.

More importantly, it ensures that the information comes directly from the same database that powers the website.

The AI isn’t guessing.

It’s querying the source of truth.

As someone who runs a reference website, that’s a pretty attractive proposition.

The Initial Design

My first goal was to keep things simple.

Rather than exposing dozens of narrowly-focused tools, I started with just two:

sovereign_on_date
line_of_succession

Those two tools cover a surprisingly large proportion of the questions people are likely to ask.

The first returns the sovereign reigning on a given date. The second returns the line of succession for a specified date, with a configurable limit on the number of entries returned.

The implementation currently caps the list at thirty people. That’s enough for most use cases while preventing someone from accidentally asking for all six thousand people currently in the line of succession.

One thing I learned quite quickly is that MCP isn’t really about exposing huge amounts of data. It’s about exposing useful questions that can be answered from your data.

MCP Is Mostly JSON-RPC

One thing that surprised me when I first started reading the specification was how little protocol code is actually required.

At its core, MCP uses JSON-RPC.

A client sends requests like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

and the server responds with:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    ...
  }
}

Once I’d written helper methods for creating standard JSON-RPC responses, most of the complexity disappeared.

The MCP module contains methods like:

sub rpc_result ($self, $id, $result)

and:

sub rpc_error ($self, $id, $code, $message)

which means the Dancer route handlers remain pleasantly small.

The protocol logic lives in one place and the web application simply delegates to it.

Separating the MCP Logic

I didn’t want protocol-specific code scattered throughout the web application.

Instead, I created a dedicated module:

package Succession::MCP;

This module is responsible for:

Initialisation
Tool discovery
Tool execution
JSON-RPC response generation
Error handling

That keeps the Dancer routes thin and makes the MCP implementation easier to test independently.

It also means that if I ever decide to expose the same MCP server through a different transport mechanism, most of the work is already done.

Tool Calls Are Mostly Adapters

One pleasant surprise was how little new application logic I actually had to write.

The MCP server needs to expose tools, but those tools ultimately just answer questions about the succession database. The code to answer those questions already existed.

For example, the application’s model layer already contained methods such as:

sovereign_on_date()
line_of_succession()

These methods power parts of the website itself, so they already encapsulate all of the business rules and database queries.

The MCP implementation simply acts as an adapter.

When a tool call arrives, the server extracts the arguments, validates them and passes them to the existing model methods:

sub _call_tool ($self, $tool_name, $args) {
  my $tool = $self->_tool_dispatch->{$tool_name};

  return $tool->($args);
}

The tool implementations themselves are deliberately thin:

sub sovereign_on_date ($self, $args) {
  my $date = $args->{date};

  my $sovereign = $self->model->sovereign_on_date($date);

  ...

}

That’s exactly how I wanted it to work.

The MCP layer doesn’t know how to calculate a line of succession or determine who was sovereign on a particular date. It simply knows how to expose those capabilities through the protocol.

This is one of the advantages of adding MCP to an existing application. If your business logic is already cleanly separated from your web interface, an MCP server often becomes surprisingly straightforward to implement.

In many ways, adding MCP feels less like building a new application and more like adding another interface alongside the website and API.

The YAML Epiphany

The most interesting design decision came a little later.

Initially, the tool definitions lived in Perl data structures.

That worked, but it quickly became obvious that I was duplicating information.

The MCP server needed tool descriptions.

The documentation page needed tool descriptions.

The schemas needed to be defined somewhere.

And every change required updating multiple places.

The obvious answer was to move all of the tool definitions into a YAML file.

The MCP module now loads its tool definitions at startup:

sub _build__tools ($self) { return LoadFile($self->tools_file); }

The result is a single source of truth.

The same YAML file drives:

The tools/list response
Tool metadata
JSON schemas
Human-readable documentation

Adding a new tool now involves updating one file and writing the code that implements it.

Everything else follows automatically.

Here’s the current YAML file:

# data/mcp-tools.yml

- name: sovereign_on_date
  description: Return the British sovereign on a given date.
  documentation: |
    Looks up the reigning British sovereign for the supplied date.

    Use this when answering questions such as “Who was sovereign on
    6 February 1952?”
  inputSchema:
    type: object
    properties:
      date:
        type: string
        description: Date in YYYY-MM-DD format.
    required:
      - date

- name: line_of_succession
  description: Return the line of succession on a given date.
  documentation: |
    Returns people in the line of succession.

    If no date is supplied, the current line of succession is returned.
  inputSchema:
    type: object
    properties:
      date:
        type: string
        description: Optional date in YYYY-MM-DD format. Omit for the current line of succession.
      limit:
        type: integer
        description: Maximum number of successors to return.
        minimum: 1
        maximum: 100
      required: []

Looking back, this is probably the part of the design I’m happiest with. It feels very Perl-ish: keep configuration as data and avoid duplicating information wherever possible.

Human Documentation Matters

One thing I noticed while exploring other MCP servers is that many of them are effectively invisible to humans.

You know an endpoint exists.

You know it speaks MCP.

But unless you inspect the protocol responses manually, you don’t really know what it does.

I decided to add a conventional web page at /mcp.

The page lists all available tools, their descriptions and their schemas.

The nice part is that there is no duplicated documentation.

The page is generated from the same YAML definitions used by the MCP server itself.

If I add a new tool tomorrow, both the machine-readable and human-readable views update automatically.

Structured Data and Text Responses

Another nice feature of MCP is that tool results can include both structured data and human-readable text.

For example, a tool response might contain:

{
  "content": [ {
    "type": "text",
    "text": "The sovereign on 14 November 1948 was George VI."
    } ],
  "structuredContent": {
    ...
  }
}

The structured content is useful for software.

The text is useful for humans and language models.

Both are generated from the same underlying data.

That gives AI clients flexibility while ensuring consistency.

Getting Listed

Once everything was working, I submitted the server to the MCP directory at mcpservers.org.

That might seem like a small step, but discoverability is important.

An MCP server hidden on a random website isn’t much use if nobody knows it exists.

Directories like that are rapidly becoming the equivalent of API catalogues for the AI era.

Being listed means developers and AI enthusiasts can find the service without first discovering the website.

Was It Worth It?

Absolutely.

The amount of code required was surprisingly small. Most of the work wasn’t implementing the protocol; it was deciding how best to expose the data.

More importantly, it opens the site up to an entirely new audience: AI agents.

Historically, websites were built for humans and APIs were built for developers.

MCP introduces a third category: services designed specifically for AI systems.

For a structured-data site like Line of Succession, that’s a natural fit.

Will MCP still be the dominant standard in five years’ time? I have no idea. The AI industry changes too quickly to make confident predictions.

But right now it has significant momentum, broad industry support and a growing ecosystem of tools.

And if nothing else, it’s rather satisfying to ask an AI who was on the throne on a particular date and know that the answer came directly from my database rather than from whatever the model happened to remember.

The post Teaching AI About the British Monarchy with MCP first appeared on Perl Hacks.

The Long Road from CGI to Containers

Dave Cross — Mon, 18 May 2026 15:36:11 +0000

One of the defining characteristics of a good programmer is an instinct for keeping implementation details in the correct layer of an application.

That sounds abstract, but it turns out to explain a huge amount of the progress we’ve made in software development over the last twenty-five years.

And nowhere is that clearer than in Perl web development.

Many of us who built web applications during the dotcom boom spent years learning this lesson the hard way.

We wrote CGI programs that:

parsed HTTP requests
generated HTML by hand
connected directly to databases
embedded SQL inline
mixed business logic with presentation
relied on Apache behaviour
assumed specific filesystem layouts
and often only worked on one particular server configuration

It all worked. Until it didn’t.

The history of Perl web development is, in many ways, the history of gradually moving implementation details into more appropriate architectural layers.

The Early CGI Years

Early Perl CGI applications were often a single giant script.

You’d open a file and see:

request handling
authentication
HTML generation
SQL queries
business logic
configuration
deployment assumptions

…all mixed together in a glorious ball of mud.

Something like this:

#!/usr/bin/perl

use CGI;
use DBI;

my $cgi = CGI->new;

print $cgi->header;
print "<html><body>";

my $dbh = DBI->connect(
  "dbi:mysql:test",
  "user",
  "pass"
);

my $sth = $dbh->prepare(
  "select * from users where id = ?"
);

$sth->execute($cgi->param('id'));

while (my $row = $sth->fetchrow_hashref) {
  print "<h1>$row->{name}</h1>";
}

print "</body></html>";

At the time, this felt perfectly normal.

And to be fair, it was a huge step forward from static HTML sites.

But the design had a fundamental problem:

Everything knew too much about everything else.

The application logic knew:

how HTTP worked
how HTML worked
how Apache launched CGI scripts
how the database worked
how the operating system was configured

Every concern leaked into every other concern.

That made systems:

hard to test
hard to reuse
hard to deploy
hard to scale
and terrifying to change

The First Big Lesson: Put Logic in Libraries

One of the first signs of a developer maturing is the realisation that application logic should live in reusable modules, not in front-end scripts.

Instead of this:

if ($user->{status} eq 'gold') {
  $discount = 0.2;
}

being embedded directly in a CGI script, it becomes:

my $discount = $user->discount_rate;

That sounds like a small change, but architecturally it’s enormous.

Now the business logic lives in a library.

And once that happens, several good things follow automatically.

Multiple Interfaces Become Possible

If the logic is in modules, then:

a web front-end
a CLI tool
a REST API
a cron job
a queue worker

…can all use the same underlying code.

The interface layer becomes thin.

The application itself becomes independent of how users interact with it.

That’s a huge increase in flexibility.

Testing Becomes Easier

Testing CGI scripts was always awkward.

Testing modules is straightforward.

You can instantiate objects, call methods, and inspect results without needing a web server or HTTP requests.

The easier code is to test, the more likely it is to be tested.

And tested code tends to survive longer.

Deployment Becomes Safer

Once the core behaviour is isolated from the interface layer, replacing the interface becomes far less risky.

You can redesign the UI without rewriting the application.

That separation is one of the foundations of maintainable software.

The PSGI Revolution

The next big architectural leap in Perl web development came with PSGI and Plack.

Younger developers may not fully appreciate how painful web deployment used to be.

In the early 2000s, moving an application between hosting environments could require substantial rewrites.

A CGI application worked one way.
A mod_perl application worked another way.
FastCGI had its own quirks.
Embedded Apache handlers behaved differently again.

Many Perl developers spent years repeatedly rewriting applications simply because deployment environments changed.

That was madness.

The deployment model is an operational concern.

It should not affect application architecture.

PSGI fixed this by defining a standard interface between web applications and web servers.

The core idea was beautifully simple:

A web application is just a function that receives an environment and returns a response.

Once that abstraction existed, applications no longer cared whether they were running:

as CGI
under mod_perl
inside FastCGI
under Starman
behind nginx
on a development laptop
or inside a cloud container

The deployment details moved down a layer.

Exactly where they belonged.

This was one of the most important architectural improvements Perl web development ever made.

And it reflected a broader truth:

Good abstractions stop lower-level implementation details leaking upward.

The Transitional Era: FatPacker and `cpanfile`

There was also an interesting intermediate stage between traditional Perl deployments and full containerisation.

For years, one of the hardest parts of deploying Perl applications was dependency management.

You’d move an application to a new server and discover:

the wrong module version
missing XS libraries
incompatible Perl versions
or an entire dependency tree that worked perfectly on the developer’s machine and nowhere else

Large parts of Perl deployment culture evolved around coping with this problem.

Tools like cpanfile improved things by making dependencies explicit and reproducible.

Instead of vaguely documenting requirements in a README, applications could formally declare:

requires 'Dancer2';
requires 'DBIx::Class';
requires 'Template';

That may seem obvious now, but it was a major improvement in deployment reliability.

Then tools like App::FatPacker went even further by packaging dependencies directly alongside applications.

Instead of relying on the target server’s Perl environment, applications could carry much of their runtime context with them.

These tools didn’t completely solve deployment portability:

system libraries still mattered
Perl versions still mattered
operating system differences still mattered

…but they represented an important shift in thinking.

The industry was gradually realising that:

deployment environments were part of the application
reproducibility mattered
and infrastructure assumptions needed to be controlled

Containers eventually pushed this idea to its logical conclusion by packaging not just Perl dependencies, but the entire runtime environment.

In hindsight, tools like cpanfile and FatPacker were stepping stones toward modern container-based deployment models.

Containers Are the Same Idea Again

Docker and containers are simply the same architectural principle repeated one layer lower.

Before containers, deployments were often fragile and highly environment-specific.

Applications depended on:

particular Linux distributions
specific Perl versions
installed system libraries
hand-configured servers
undocumented setup steps

Developers became experts in “works on my machine”.

Operations teams became experts in swearing.

Containers changed the model.

Instead of deploying:

source code

…you deploy:

a complete runtime environment

Now the application no longer cares whether it runs:

on bare metal
on a VPS
in Kubernetes
in ECS
in Cloud Run
or on someone’s laptop

Again:

infrastructure concerns move downward
application concerns stay upward

The boundaries become cleaner.

The Pattern Repeats Everywhere

Once you notice this pattern, you see it throughout software engineering.

Templates

Template systems separate:

presentation

from

application logic

HTML should not contain database code.

Business logic should not contain giant blobs of HTML.

ORMs and Database Layers

DBI separates applications from database engines.

ORMs separate applications from raw SQL structure.

Again:

implementation details move downward

Configuration

Configuration belongs outside code.

Deployment-specific values should not be embedded in applications.

APIs

Clients should not care whether data comes from:

PostgreSQL
Redis
another service
a queue
flat files
or magic elves

That’s the implementation’s problem.

The Goal Is Not Abstraction for Its Own Sake

Of course, experienced developers also know that abstractions can become ridiculous.

Some abstractions simplify systems.

Others merely hide complexity behind six additional layers of YAML.

Joel Spolsky’s “Law of Leaky Abstractions” remains painfully relevant.

The goal is not abstraction itself.

The goal is to isolate genuinely volatile details.

Good abstractions protect systems from change.

Bad abstractions merely obscure reality.

The Real Skill

The deeper lesson here is that software architecture is largely about deciding:

“What belongs where?”

Experienced developers develop an instinct for:

which details are likely to change
which layers should know about which concerns
and where boundaries should exist

That instinct is often more important than language choice, frameworks, or technology stacks.

And if you spent the early 2000s rewriting CGI applications to run under mod_perl, you probably learned that lesson the hard way.

The post The Long Road from CGI to Containers first appeared on Perl Hacks.

How I Cross-Post Blog Articles (Without Making It Complicated)

Dave Cross — Tue, 28 Apr 2026 15:33:29 +0000

Someone asked me on LinkedIn recently how to cross-post blog content from a GitHub Pages site to places like Medium, dev.to and LinkedIn.

I started writing a quick reply and, as often happens, it turned into something longer. So here’s the slightly more organised version.

Two different problems

There are actually two separate things people mean when they ask this.

1. Sharing links on social media

This is the easy one.

When I publish a post, I’ll usually share it by:

pasting the link
adding a short description
maybe tweaking the wording per platform

The only slightly technical thing worth doing here is making sure your site has Open Graph tags set up properly.

That ensures:

the right title appears
the right description is used
and, importantly, the right image is shown

If you don’t do this, your carefully written post ends up looking like a random bare link.

What about “Share to…” buttons?

Many blogging platforms (and themes) offer “Share to Facebook/LinkedIn/etc.” buttons.

They:

generate a pre-filled post
save a bit of time

I don’t tend to use them – I prefer writing a slightly different intro per platform – but they’re perfectly reasonable if you want something quick and consistent.

2. Reposting the article elsewhere

This is where it gets more interesting.

My usual workflow is:

write on my own site (WordPress in my case, but GitHub Pages is fine)
then repost to other platforms

The two I use most are Medium and dev.to – and they take slightly different approaches.

First requirement: you need a web feed

If you want any level of automation, your site needs an RSS/Atom feed.

WordPress: you get this automatically
GitHub Pages: depends how your site is built

A lot of people use Jekyll on GitHub Pages (it’s the default and best-supported option), but it’s not the only choice — you can also use other static site generators or even pre-built HTML.

Whichever approach you use, you’ll need to make sure it produces a web feed.

If you’re using Jekyll

Add the official feed plugin:

plugins:
- jekyll-feed

GitHub Pages supports this plugin natively, so there’s no extra build step needed.

Your feed will usually be available at:

/feed.xml

If you’re using something else

Most static site generators (Hugo, Eleventy, Astro, etc.) can generate feeds, but:

it’s often not enabled by default
the configuration varies

So you’ll need to:

check the documentation for your tool
enable or add a feed generator
confirm the feed URL works

That feed is what tools like dev.to use to discover your posts.

Medium: “Import a story”

Medium has a built-in Import a story feature.

You give it the URL of your original post and it:

pulls in the content
recreates the article
lets you edit it before publishing

It works surprisingly well.

The only slight downside is that it always takes me a few minutes to find the option. It’s on your Stories page (when you’re logged in). Look for the big button in the top right corner.

dev.to: RSS-based automation

dev.to does something a bit cleverer.

You can:

point it at your RSS/Atom feed
and it will automatically create draft posts for new articles

A few notes from experience:

it can take a few hours for drafts to appear
formatting is usually good but you’ll probably want to tweak it a bit
it often misses the featured image, so I add that manually

The really important bit: canonical URLs

This is the part that many people miss.

When you repost content, you are technically creating duplicate content – which search engines don’t love.

However…

If you use the official import tools:

Medium
dev.to

…they both add a canonical link back to your original post.

That’s the equivalent of saying:

“This content originally lives over here – treat that as the primary version.”

Which means:

your original site gets the SEO benefit
you don’t get penalised for duplication

If you’re manually copying and pasting, you need to be careful about this – or at least be aware of the trade-off.

What about LinkedIn?

LinkedIn is a bit different.

As far as I’m aware, there isn’t a clean equivalent of:

Medium’s import tool
or dev.to’s RSS integration

It’s worth checking – platforms change – but I haven’t found anything comparable.

So my approach is:

write a short summary
link to the original post

That also tends to fit LinkedIn better as a platform.

I’ve seen various guides suggesting ways to automate LinkedIn reposting, but many of them rely on long-dead platforms or brittle integrations. As far as I can tell, there’s no clean, supported equivalent of Medium’s import tool or dev.to’s RSS integration. These days, I treat LinkedIn as a place to promote posts rather than republish them.

Is any of this automated?

A bit, but not completely.

Medium: semi-automated (import tool)
dev.to: semi-automated (RSS → draft)
LinkedIn: manual

You could build a fully automated pipeline with APIs and scripts.

But in practice:

a small amount of manual editing is useful
each platform benefits from slightly different positioning

So I don’t try to over-automate it.

The takeaway

There’s no standard protocol for cross-posting blog content.

What you actually have is:

a few helpful platform features
a bit of light automation
and some copy-and-paste

And honestly, that works perfectly well.

Like most things on the web, there’s no single ‘right’ way to do this — just a collection of tools that mostly work if you don’t try to be too clever.

If you’d like help building this kind of thing without overcomplicating it, there’s a brief overview of what I do here:

https://davecross.co.uk/services/

The post How I Cross-Post Blog Articles (Without Making It Complicated) appeared first on Davblog.

Summarising a Month of Git Activity with Perl (and a Little Help from AI)

Dave Cross — Sun, 12 Apr 2026 15:46:52 +0000

Every month, I write a newsletter which (among other things) discusses some of the technical projects I’ve been working on. It’s a useful exercise — partly as a record for other people, but mostly as a way for me to remember what I’ve actually done.

Because, as I’m sure you’ve noticed, it’s very easy to forget.

So this month, I decided to automate it.

(And, if you’re interested in the end result, this is also a good excuse to mention that the newsletter exists. Two birds, one stone.)

The Problem

All of my Git repositories live somewhere under /home/dave/git. Over time, that’s become… less organised than it might be. Some repos are directly under that directory, others are buried a couple of levels down, and I’m fairly sure there are a few I’ve completely forgotten about.

What I wanted was:

Given a month and a year
Find all Git repositories under that directory
Identify which ones had commits in that month
Summarise the work done in each repo

The first three are straightforward enough. The last one is where things get interesting.

Finding the Repositories

The first step is walking the directory tree and finding .git directories. This is a classic Perl task — File::Find still does exactly what you need.

use v5.40;
use File::Find;

sub find_repos ($root) {
  my @repos;

  find(
    sub {
      return unless $_ eq '.git';
      push @repos, $File::Find::dir;
    },
    $root
  );

  return @repos;
}

This gives us a list of repository directories to inspect. It’s simple, robust, and doesn’t require any external dependencies.

(There are, of course, other ways to do this — you could shell out to fd or find, for example — but keeping it in Perl keeps everything nicely self-contained.)

Getting Commits for a Month

For each repo, we can run git log with appropriate date filters.

sub commits_for_month ($repo, $since, $until) {
  my $cmd = sprintf(
    q{git -C %s log --since="%s" --until="%s" --pretty=format:"%%s"},
    $repo, $since, $until
  );

  my @commits = `$cmd`;
  chomp @commits;

  return @commits;
}

Where $since and $until define the month we’re interested in. I’ve been using something like:

my $since = "$year-$month-01";
my $until = "$year-$month-31"; # good enough for this purpose

Yes, that’s a bit hand-wavy around month lengths. No, it doesn’t matter in practice. Sometimes “good enough” really is good enough.

A Small Gotcha

It turns out I have a few repositories where I never got around to making a first commit. In that case, git log helpfully explodes with:

fatal: your current branch ‘master’ does not have any commits yet

Which is fair enough — but not helpful in a script that’s supposed to quietly churn through dozens of repositories.

The fix is simply to ignore failures:

my @commits = `$cmd 2>/dev/null`;

If there are no commits, we just get an empty list and move on. No warnings, no noise.

This is one of those little bits of defensive programming that makes the difference between a script you run once and a script you’re happy to run every month.

Summarising the Work

Once we have a list of commit messages, we can summarise them.

And this is where I cheated slightly.

I used OpenAPI::Client::OpenAI to feed the commit messages into an LLM and ask it to produce a short summary.

Something along these lines:

use OpenAPI::Client::OpenAI;

sub summarise_commits ($commits) {
  my $client = OpenAPI::Client::OpenAI->new(
    api_key => $ENV{OPENAI_API_KEY},
  );

  my $text = join "\n", @$commits;

  my $response = $client->chat->completions->create({
    model => 'gpt-4.1-mini',
    messages => [{
      role => 'user',
      content => "Summarise the following commit messages:\n\n$text",
    }],
  });

 return $response->choices->[0]->message->content;
}

Is this overkill? Almost certainly.

Could I have written some heuristics to group and summarise commit messages? Possibly.

Would it have been as much fun? Definitely not.

And in practice, it works remarkably well. Even messy, inconsistent commit messages tend to turn into something that looks like a coherent summary of work.

Putting It Together

For each repo:

Get commits for the month
Skip if there are none
Generate a summary
Print the repo name and summary

The output looks something like:

my-project
-----------
Refactored database layer, added caching, and fixed several edge-case bugs.

another-project
---------------
Initial scaffolding, basic API endpoints, and deployment configuration.

Which is already a pretty good starting point for a newsletter.

A Nice Side Effect

One unexpected benefit of this approach is that it surfaces projects I’d forgotten about.

Because the script walks the entire directory tree, it finds everything — including half-finished experiments, abandoned ideas, and repos I created at 11pm and never touched again.

Sometimes that’s useful. Sometimes it’s mildly embarrassing.

But it’s always interesting.

What Next?

This is very much a first draft.

It works, but it’s currently a script glued together with shell commands and assumptions about my directory structure. The obvious next step is to:

Turn it into a proper module
Add tests
Clean up the API
Release it to CPAN

At that point, it becomes something other people might actually want to use — not just a personal tool with hard-coded paths and questionable date handling.

A Future Enhancement

One idea I particularly like is to run this automatically using GitHub Actions.

For example:

Run monthly
Generate summaries for that month
Commit the results to a repository
Publish them via GitHub Pages

Over time, that would build up a permanent, browsable record of what I’ve been working on.

It’s a nice combination of:

automation
documentation
and a gentle nudge towards accountability

Which is either a fascinating historical archive…

…or a slightly alarming reminder of how many half-finished projects I have.

Closing Thoughts

This started as a small piece of automation to help me write a newsletter. But it’s turned into a nice example of what Perl is still very good at:

Gluing systems together
Wrapping command-line tools
Handling messy real-world data
Adding just enough intelligence to make the output useful

And, occasionally, outsourcing the hard thinking to a machine.

The code (such as it is currently is) is on GitHub at https://github.com/davorg/git-month-summary.

If you’re interested in the kind of projects this helps summarise, you can find my monthly newsletter over on Substack.

And if I get round to turning this into a CPAN module, I’ll let you know – well, if you’re subscribed to the newsletter!

The post Summarising a Month of Git Activity with Perl (and a Little Help from AI) first appeared on Perl Hacks.

Writing a TOON Module for Perl

Dave Cross — Sun, 29 Mar 2026 17:46:14 +0000

Every so often, a new data serialisation format appears and people get excited about it. Recently, one of those formats is TOON — Token-Oriented Object Notation. As the name suggests, it’s another way of representing the same kinds of data structures that you’d normally store in JSON or YAML: hashes, arrays, strings, numbers, booleans and nulls.

So the obvious Perl question is: “Ok, where’s the CPAN module?”

This post explains what TOON is, why some people think it’s useful, and why I decided to write a Perl module for it — with an interface that should feel very familiar to anyone who has used JSON.pm.

I should point out that I knew about Data::Toon but I wanted something with an interface that was more like JSON.pm.

—

What TOON Is

TOON stands for Token-Oriented Object Notation. It’s a textual format for representing structured data — the same data model as JSON:

Objects (hashes)
Arrays
Strings
Numbers
Booleans
Null

The idea behind TOON is that it is designed to be easy for both humans and language models to read and write. It tries to reduce punctuation noise and make the structure of data clearer.

If you think of the landscape like this:

Format	Human-friendly	Machine-friendly	Very common
JSON	Medium	Very	Yes
YAML	High	Medium	Yes
TOON	High	High	Not yet

TOON is trying to sit in the middle: simpler than YAML, more readable than JSON.

Whether it succeeds at that is a matter of taste — but it’s an interesting idea.

—

TOON vs JSON vs YAML

It’s probably easiest to understand TOON by comparing it to JSON and YAML. Here’s the same “person” record written in all three formats.

JSON

{  
  "name": "Arthur Dent",
  "age": 42,
  "email": "arthur@example.com",
  "alive": true,
  "address": {
    "street": "High Street",
    "city": "Guildford"
   },
  "phones": [
    "01234 567890",
    "07700 900123"
  ]
}

YAML

name: Arthur Dent  
age: 42  
email: arthur@example.com  
alive: true  
address:  
  street: High Street  
  city: Guildford  
phones:  
  – 01234 567890  
  – 07700 900123

TOON

name: Arthur Dent
age: 42
email: arthur@example.com”
alive: true
address:
  street: High Street 
  city: Guildford
phones[2]: 01234 567890,07700 900123

You can see that TOON sits somewhere between JSON and YAML:

Less punctuation and quoting than JSON
More explicit structure than YAML
Still very easy to parse
Still clearly structured for machines

That’s the idea, anyway.

—

Why People Think TOON Is Useful

The current interest in TOON is largely driven by AI/LLM workflows.

People are using it because:

It is easier for humans to read than JSON.
It is less ambiguous and complex than YAML.
It maps cleanly to the JSON data model.
It is relatively easy to parse.
It works well in prompts and generated output.

In other words, it’s not trying to replace JSON for APIs, and it’s not trying to replace YAML for configuration files. It’s aiming at the space where humans and machines are collaborating on structured data.

You may or may not buy that argument — but it’s an interesting niche.

—

Why I Wrote a Perl Module

I don’t have particularly strong opinions about TOON as a format. It might take off, it might not. We’ve seen plenty of “next big data format” ideas over the years.

But what I do have a strong opinion about is this:

If a data format exists, then Perl should have a CPAN module for it that works the way Perl programmers expect.

Perl already has very good, very consistent interfaces for data serialisation:

JSON
YAML
Storable
Sereal

They all tend to follow the same pattern, particularly the object-oriented interface:

use JSON;  
my $json = JSON->new->pretty->canonical;  
my $text = $json->encode($data);  
my $data = $json->decode($text);

So I wanted a TOON module that worked the same way.

—

Design Goals

When designing the module, I had a few simple goals.

1. Familiar OO Interface

The primary interface should be object-oriented and feel like JSON.pm:

use TOON;  
my $toon = TOON->new  
               ->pretty  
               ->canonical  
               ->indent(2);  
my $text = $toon->encode($data);  
my $data = $toon->decode($text);

If you already know JSON, you already know how to use TOON.

There are also convenience functions, but the OO interface is the main one.

2. Pure Perl Implementation

Version 0.001 is pure Perl. That means:

Easy to install
No compiler required
Works everywhere Perl works

If TOON becomes popular and performance matters, someone can always write an XS backend later.

3. Clean Separation of Components

Internally, the module is split into:

Tokenizer – turns text into tokens
Parser – turns tokens into Perl data structures
Emitter – turns Perl data structures into TOON text
Error handling – reports line/column errors cleanly

This makes it easier to test and maintain.

4. Do the Simple Things Well First

Version 0.001 supports:

Scalars
Arrayrefs
Hashrefs
undef → null
Pretty printing
Canonical key ordering

It does not (yet) try to serialise blessed objects or do anything clever. That can come later if people actually want it.

—

Example Usage (OO Style)

Here’s a simple Perl data structure:

my $data = {
  name => "Arthur Dent",
  age => 42,
  drinks => ["tea", "coffee"],
  alive => 1,  
};

Encoding

use TOON;  
my $toon = TOON->new->pretty->canonical;  
my $text = $toon->encode($data);  
print $text;

Decoding

use TOON;  
my $toon = TOON->new;  
my $data = $toon->decode($text);  
print $data->{name};

Convenience Functions

use TOON qw(encode_toon decode_toon);  
my $text = encode_toon($data);  
my $data = decode_toon($text);

But the OO interface is where most of the flexibility lives.

—

Command Line Tool

There’s also a command-line tool, toon_pp, similar to json_pp:

cat data.toon | toon_pp

Which will pretty-print TOON data.

—

Final Thoughts

I don’t know whether TOON will become widely used. Predicting the success of data formats is a fool’s game. But the cost of supporting it in Perl is low, and the potential usefulness is high enough to make it worth doing.

And fundamentally, this is how CPAN has always worked:

See a problem. Write a module. Upload it. See if anyone else finds it useful.

So now Perl has a TOON module. And if you already know how to use JSON.pm, you already know how to use it.

That was the goal.

The post Writing a TOON Module for Perl first appeared on Perl Hacks.

Still on the [b]leading edge

Dave Cross — Sat, 21 Mar 2026 11:14:06 +0000

About eighteen months ago, I wrote a post called On the Bleading Edge about my decision to start using Perl’s new class feature in real code. I knew I was getting ahead of parts of the ecosystem. I knew there would be occasional pain. I decided the benefits were worth it.

I still think that’s true.

But every now and then, the bleading edge reminds you why it’s called that.

Recently, I lost a couple of days to a bug that turned out not to be in my code, not in the module I was installing, and not even in the module that module depended on — but in the installer’s understanding of modern Perl syntax.

This is the story.

The Symptom

I was building a Docker image for Aphra. As part of the build, I needed to install App::HTTPThis, which depends on Plack::App::DirectoryIndex, which depends on WebServer::DirIndex.

The Docker build failed with this error:

#13 45.66 --> Working on WebServer::DirIndex
#13 45.66 Fetching https://www.cpan.org/authors/id/D/DA/DAVECROSS/WebServer-DirIndex-0.1.3.tar.gz ... OK
#13 45.83 Configuring WebServer-DirIndex-v0.1.3 ... OK
#13 46.21 Building WebServer-DirIndex-v0.1.3 ... OK
#13 46.75 Successfully installed WebServer-DirIndex-v0.1.3
#13 46.84 ! Installing the dependencies failed: Installed version (undef) of WebServer::DirIndex is not in range 'v0.1.0'
#13 46.84 ! Bailing out the installation for Plack-App-DirectoryIndex-v0.2.1.

Now, that’s a deeply confusing error message.

It clearly says that WebServer::DirIndex was successfully installed. And then immediately says that the installed version is undef and not in the required range.

At this point you start wondering if you’ve somehow broken version numbering, or if there’s a packaging error, or if the dependency chain is wrong.

But the version number in WebServer::DirIndex was fine. The module built. The tests passed. Everything looked normal.

So why did the installer think the version was undef?

When This Bug Appears

This only shows up in a fairly specific situation:

A module uses modern Perl class syntax
The module defines a $VERSION
Another module declares a prerequisite with a specific version requirement
The installer tries to check the installed version without loading the module
It uses Module::Metadata to extract $VERSION
And the version of Module::Metadata it is using doesn’t properly understand class

If you don’t specify a version requirement, you’ll probably never see this. Which is why I hadn’t seen it before. I don’t often pin minimum versions of my own modules, but in this case, the modules are more tightly coupled than I’d like, and specific versions are required.

So this bug only appears when you combine:

modern Perl syntax + version checks + older toolchain

Which is pretty much the definition of “bleading edge”.

The Real Culprit

The problem turned out to be an older version of Module::Metadata that had been fatpacked into cpanm.

cpanm uses Module::Metadata to inspect modules and extract $VERSION without loading the module. But the older Module::Metadata didn’t correctly understand the class keyword, so it couldn’t work out which package the $VERSION belonged to.

So when it checked the installed version, it found… nothing.

Hence:

Installed version (undef) of WebServer::DirIndex is not in range ‘v0.1.0’

The version wasn’t wrong. The installer just couldn’t see it.

An aside, you may find it amusing to hear an anecdote from my attempts to debug this problem.

I spun up a new Ubuntu Docker container, installed cpanm and tried to install Plack::App::DirectoryIndex. Initially, this gave the same error message. At least the problem was easily reproducible.

I then ran code that was very similar to the code cpanm uses to work out what a module’s version is.

$ perl -MModule::Metadata -E'say Module::Metadata->new_from_module("WebServer::DirIndex")->version'

This displayed an empty string. I was really onto something here. Module::Metadata couldn’t find the version.

I was using Module::Metadata version 1.000037 and, looking at the change log on CPAN, I saw this:

1.000038 2023-04-28 11:25:40Z

- detects "class" syntax

I installed 1.000038 and reran my command.

$ perl -MModule::Metadata -E'say Module::Metadata->new_from_module("WebServer::DirIndex")->version'
0.1.3

That seemed conclusive. Excitedly, I reran the Docker build.

It failed again.

You’ve probably worked out why. But it took me a frustrating half an hour to work it out.

cpanm doesn’t use the installed version of Module::Metadata. It uses its own, fatpacked version. Updating Module::Metadata wouldn’t fix my problem.

The Workaround

I found a workaround. That was to add a redundant package declaration alongside the class declaration, so older versions of Module::Metadata can still identify the package that owns $VERSION.

So instead of just this:

class WebServer::DirIndex {
  our $VERSION = '0.1.3';
  ...
}

I now have this:

package WebServer::DirIndex;

class WebServer::DirIndex {
  our $VERSION = '0.1.3';
  ...
}

It looks unnecessary. And in a perfect world, it would be unnecessary.

But it allows older tooling to work out the version correctly, and everything installs cleanly again.

The Proper Fix

Of course, the real fix was to update the toolchain.

So I raised an issue against App::cpanminus, pointing out that the fatpacked Module::Metadata was too old to cope properly with modules that use class.

Tatsuhiko Miyagawa responded very quickly, and a new release of cpanm appeared with an updated version of Module::Metadata.

This is one of the nice things about the Perl ecosystem. Sometimes you report a problem and the right person fixes it almost immediately.

When Do I Remove the Workaround?

This leaves me with an interesting question.

The correct fix is “use a recent cpanm”.

But the workaround is “add a redundant package line so older tooling doesn’t get confused”.

So when do I remove the workaround?

The answer is probably: not yet.

Because although a fixed cpanm exists, that doesn’t mean everyone is using it. Old Docker base images, CI environments, bootstrap scripts, and long-lived servers can all have surprisingly ancient versions of cpanm lurking in them.

And the workaround is harmless. It just offends my sense of neatness slightly.

So for now, the redundant package line stays. Not because modern Perl needs it, but because parts of the world around modern Perl are still catching up.

Life on the Bleading Edge

This is what life on the bleading edge actually looks like.

Not dramatic crashes. Not language bugs. Not catastrophic failures.

Just a tool, somewhere in the install chain, that looks at perfectly valid modern Perl code and quietly decides that your module doesn’t have a version number.

And then you lose two days proving that you are not, in fact, going mad.

But I’m still using class. And I’m still happy I am.

You just have to keep an eye on the whole toolchain — not just the language — when you decide to live a little closer to the future than everyone else.

The post Still on the [b]leading edge first appeared on Perl Hacks.

Your README Is Already a Website

Dave Cross — Sat, 28 Feb 2026 17:42:48 +0000

Announcing `readme-to-index` — My First GitHub Marketplace Release 🎉

Today I published my first GitHub Action to the Marketplace.

It’s called readme-to-index, and it does something very simple:

It turns your README.md into a clean, styled index.html.

That’s it.

No Jekyll.
No Ruby.
No themes.
No _config.yml.
No implicit behaviour.

Just Markdown → HTML → Done.

Why I Built It

I have a lot of small projects.

Many of them already have good READMEs. In fact, for most of them, the README is the documentation.

So the obvious question is:

Why create a separate site when the README already exists?

GitHub Pages + Jekyll is great. But for small libraries and utilities, it can feel like overkill.

I wanted something:

Minimal
Deterministic
Easy to drop into any workflow
Friendly to CI pipelines
With zero hidden conventions

So I built a GitHub Action that does exactly one thing:

README.md → index.html

Styled using Simple.css (by default, but you can use any stylesheet you like).

What It Does

Converts README.md to index.html using Pandoc
Automatically sets the HTML <title> from the first # Heading
Applies Simple.css for clean, classless styling
Suppresses Pandoc’s injected syntax-highlighting CSS
Leaves your original README untouched

Your README remains the canonical source of truth.

Usage

Add this to your workflow:

- uses: davorg/readme-to-index@v1
  with:
    output: _site/index.html

Then deploy using the standard GitHub Pages artifact flow.

Available Options

The action supports a few optional inputs:

`readme`

Path to the Markdown source file.

Default: README.md

`output`

Path to the generated HTML file.

Default: index.html

`css_url`

CSS stylesheet to include in the generated HTML.

Default: https://cdn.simplecss.org/simple.min.css

`install_pandoc`

Whether to install Pandoc automatically using apt-get.

Default: true

Set this to false if your workflow already installs Pandoc.

`extra_pandoc_args`

Additional arguments passed directly to the Pandoc command.

Example:

- uses: davorg/readme-to-index@v1
  with:
    extra_pandoc_args: "--toc"

Enabling GitHub Pages

For this to deploy as a website, you’ll need to enable GitHub Pages in your repository settings.

Go to:

Repository → Settings → Pages → Build and deployment

Set:

Source: GitHub Actions

That’s it. The workflow will handle the rest.

Example Complete Workflow

Here’s a minimal working example:

name: Publish README to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  pages:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - uses: davorg/readme-to-index@v1
        with:
          output: _site/index.html

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: _site

      - id: deployment
        uses: actions/deploy-pages@v4

Why Not Just Use Jekyll?

You absolutely can.

But this approach has two real advantages:

1. Simplicity

There’s no Ruby toolchain.

There are no implicit layouts.

There are no theme conventions to understand.

It takes one Markdown file and produces one HTML file.

That’s it.

2. Pipeline-Friendly

Because it’s "just a step", you can use it:

As part of a release build
In CI pipelines
Before publishing documentation artifacts
Outside GitHub entirely

It doesn’t rely on GitHub Pages’ default behaviour.

It works wherever Pandoc runs.

A Small Milestone

Shipping something to the GitHub Marketplace feels surprisingly significant.

It’s a tiny tool.
It does one thing.
But it does it cleanly.

That’s the kind of tooling I like building.

If you’re interested:

👉 https://github.com/marketplace/actions/readme-to-index-html

Feedback welcome. Stars appreciated. Minimalism encouraged.

Treating GitHub Copilot as a Contributor

Dave Cross — Sun, 22 Feb 2026 11:51:15 +0000

For some time, we’ve talked about GitHub Copilot as if it were a clever autocomplete engine.

It isn’t.

Or rather, that’s not all it is.

The interesting thing — the thing that genuinely changes how you work — is that you can assign GitHub issues to Copilot.

And it behaves like a contributor.

Over the past day, I’ve been doing exactly that on my new CPAN module, WebServer::DirIndex. I’ve opened issues, assigned them to Copilot, and watched a steady stream of pull requests land. Ten issues closed in about a day, each one implemented via a Copilot-generated PR, reviewed and merged like any other contribution.

That still feels faintly futuristic. But it’s not “vibe coding”. It’s surprisingly structured.

Let me explain how it works.

It Starts With a Proper Issue

This workflow depends on discipline. You don’t type “please refactor this” into a chat window. You create a proper GitHub issue. The sort you would assign to another human maintainer. For example, here are some of the recent issues Copilot handled in WebServer::DirIndex:

Add CPAN scaffolding
Update the classes to use Feature::Compat::Class
Replace DirHandle
Add WebServer::DirIndex::File
Move render() method
Use :reader attribute where useful
Remove dependency on Plack

Each one was a focused, bounded piece of work. Each one had clear expectations.

The key is this: Copilot works best when you behave like a maintainer, not a magician.

You describe the change precisely. You state constraints. You mention compatibility requirements. You indicate whether tests need to be updated.

Then you assign the issue to Copilot.

And wait.

The Pull Request Arrives

After a few minutes — sometimes ten, sometimes less — Copilot creates a branch and opens a pull request.

The PR contains:

Code changes
Updated or new tests
A descriptive PR message

And because it’s a real PR, your CI runs automatically. The code is evaluated in the same way as any other contribution.

This is already a major improvement over editor-based prompting. The work is isolated, reviewable, and properly versioned.

But the most interesting part is what happens in the background.

Watching Copilot Think

If you visit the Agents tab in the repository, you can see Copilot reasoning through the issue.

It reads like a junior developer narrating their approach:

Interpreting the problem
Identifying the relevant files
Planning changes
Considering test updates
Running validation steps

And you can interrupt it.

If it starts drifting toward unnecessary abstraction or broad refactoring, you can comment and steer it:

Please don’t change the public API.
Avoid experimental Perl features.
This must remain compatible with Perl 5.40.

It responds. It adjusts course.

This ability to intervene mid-flight is one of the most useful aspects of the system. You are not passively accepting generated code — you’re supervising it.

Teaching Copilot About Your Project

Out of the box, Copilot doesn’t really know how your repository works. It sees code, but it doesn’t know policy.

That’s where repository-level configuration becomes useful.

1. Custom Repository Instructions

GitHub allows you to provide a .github/copilot-instructions.md file that gives Copilot repository-specific guidance. The documentation for this lives here:

Adding repository custom instructions for GitHub Copilot

When GitHub offers to generate this file for you, say yes.

Then customise it properly.

In a CPAN module, I tend to include:

Minimum supported Perl version
Whether Feature::Compat::Class is preferred
Whether experimental features are forbidden
CPAN layout expectations (lib/, t/, etc.)
Test conventions (Test::More, no stray diagnostics)
A strong preference for not breaking the public API

Without this file, Copilot guesses.

With this file, Copilot aligns itself with your house style.

That difference is impressive.

2. Customising the Copilot Development Environment

There’s another piece that many people miss: Copilot can run a special workflow event called copilot_agent_setup.

You can define a workflow that prepares the environment Copilot works in. GitHub documents this here:

Customizing the development environment for GitHub Copilot coding agent

In my Perl projects, I use this standard setup:

name: Copilot Setup Steps

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
  steps:
    - name: Check out repository
      uses: actions/checkout@v4

    - name: Set up Perl 5.40
      uses: shogo82148/actions-setup-perl@v1
      with:
        perl-version: '5.40'

    - name: Install dependencies
      run: cpanm --installdeps --with-develop --notest .

(Obviously, that was originally written for me by Copilot!)

This does two important things.

Firstly, it ensures Copilot is working with the correct Perl version.

Secondly, it installs the distribution dependencies, meaning Copilot can reason in a context that actually resembles my real development environment.

Without this workflow, Copilot operates in a kind of generic space.

With it, Copilot behaves like a contributor who has actually checked out your code and run cpanm.

That’s a useful difference.

Reviewing the Work

This is the part where it’s important not to get starry-eyed.

I still review the PR carefully.

I still check:

Has it changed behaviour unintentionally?
Has it introduced unnecessary abstraction?
Are the tests meaningful?
Has it expanded scope beyond the issue?

I check out the branch and run the tests. Exactly as I would with a PR from a human co-worker.

You can request changes and reassign the PR to Copilot. It will revise its branch.

The loop is fast. Faster than traditional asynchronous code review.

But the responsibility is unchanged. You are still the maintainer.

Why This Feels Different

What’s happening here isn’t just “AI writing code”. It’s AI integrated into the contribution workflow:

Issues
Structured reasoning
Pull requests
CI
Review cycles

That architecture matters.

It means you can use Copilot in a controlled, auditable way.

In my experience with WebServer::DirIndex, this model works particularly well for:

Mechanical refactors
Adding attributes (e.g. :reader where appropriate)
Removing dependencies
Moving methods cleanly
Adding new internal classes

It is less strong when the issue itself is vague or architectural. Copilot cannot infer the intent you didn’t articulate.

But given a clear issue, it’s remarkably capable — even with modern Perl using tools like Feature::Compat::Class.

A Small but Important Point for the Perl Community

I’ve seen people saying that AI tools don’t handle Perl well. That has not been my experience.

With a properly described issue, repository instructions, and a defined development environment, Copilot works competently with:

Modern Perl syntax
CPAN distribution layouts
Test suites
Feature::Compat::Class (or whatever OO framework I’m using on a particular project)

The constraint isn’t the language. It’s how clearly you explain the task.

The Real Shift

The most interesting thing here isn’t that Copilot writes Perl. It’s that GitHub allows you to treat AI as a contributor.

You file an issue.
You assign it.
You supervise its reasoning.
You review its PR.

It’s not autocomplete. It’s not magic. It’s just another developer on the project. One who works quickly, doesn’t argue, and reads your documentation very carefully.

Have you been using AI tools to write or maintain Perl code? What successes (or failures!) have you had? Are there other tools I should be using?

Links

If you want to have a closer look at the issues and PRs I’m talking about, here are some links?

The post Treating GitHub Copilot as a Contributor first appeared on Perl Hacks.

I Built a Tiny Domain Inventory Tool (Because I Used to Buy Too Many Domains)

Dave Cross — Sun, 08 Feb 2026 12:22:22 +0000

(Or: how I stopped losing track of the domains I swore I wouldn’t buy)

I used to be a serial domain-buyer.

Not in a dramatic, “lost a fortune” way — just lots of “oh, that might be useful one day” moments spread over many years. At one point, I honestly couldn’t tell you exactly what I owned, where it was registered, or what half of it pointed at.

I’m mostly better now. Mostly.

But I still own more domains than I like to admit, and I wanted a simple, honest way to see what I’ve got without:

another SaaS subscription
a spreadsheet that immediately goes stale
or building a backend I’d then have to maintain forever

So I built this instead:

👉 https://davorg.dev/mydomains/
👉 Source code: https://github.com/davorg/mydomains

It’s a small, static, browser-only tool for keeping track of domains, their DNS, and where they’re hosted — and it turns out to be surprisingly useful.

What I wanted (and what I very deliberately didn’t)

I wanted something that:

runs entirely in the browser
stores its data locally
can be hosted as static files
gives me useful facts, not a false sense of certainty

I explicitly didn’t want:

accounts
logins
databases
background jobs
“AI-powered insights” (whatever that would even mean here)

This is a tool for me. I trust myself with my own data.

If that resonates with you, read on.

What the tool does

At its core, it’s just an inventory:

a list of domains you own
the hostnames you care about (@, www, mail, etc.)
some notes and keywords so future-you knows why you bought it

On top of that, it can enrich each domain with:

DNS data
- NS, MX, TXT for the domain
- A / AAAA / CNAME for each host
RDAP data
- registrar
- expiry date
- registration status
Best-effort guesses
- DNS provider
- hosting provider per host

Everything is opt-in and cached. Nothing happens unless you click “refresh”.

Architecture: aggressively boring (by design)

There are three files that matter:

index.html
style.css
script.js

No build step. No framework. No external dependencies beyond public HTTP APIs.

All state lives in localStorage under a single key:

const STORAGE_KEY = 'domainInventory.v1';

If you clear your browser data, it’s gone. Which is why import/export exists.

That’s not a bug — that’s the trade-off.

DNS and RDAP: best-effort, not gospel

DNS is fetched using Google’s DNS-over-HTTPS endpoint:

https://dns.google/resolve?name=example.com&type=A

RDAP is fetched via rdap.org, with a couple of TLD-specific exceptions where needed.

This immediately gives you two realities to accept:

Not everything has RDAP
CORS sometimes says no

The code treats RDAP as optional. If it works, great. If not, nothing breaks.

That pattern shows up a lot in this project.

Provider guessing (aka “useful lies”)

One of the more interesting parts was deciding how far to go with interpretation.

DNS provider detection

This is intentionally simple:

function guessDnsProvider(nsList) {
  const nsLower = (nsList || []).map(n => n.toLowerCase());

  if (nsLower.some(n => n.includes('cloudflare.com'))) {
    return 'Cloudflare';
  }
  if (nsLower.some(n => n.includes('awsdns'))) {
    return 'AWS Route 53';
  }
  if (nsLower.some(n => n.includes('gandi.net'))) {
    return 'Gandi';
  }
  return 'Unknown';
}

Is it exhaustive? No.
Is it useful for my domains? Yes.

That’s a recurring theme here.

Hosting provider detection (and Cloudflare honesty)

Hosting detection looks at:

CNAME targets
A / AAAA addresses
known IP ranges
known patterns (.github.io, .cloudfront.net, .a.run.app, etc.)

But DNS can lie — or at least obscure.

So if a host resolves to Cloudflare IPs, the tool does this:

If it recognised the origin → “GitHub Pages (via Cloudflare)”
Otherwise → “Unknown (via Cloudflare)”

If the data doesn’t support a confident claim, I’d rather say “I don’t know” than pretend.

Caching with intent

All fetched data is cached per domain, along with a timestamp:

dom.cache.lastChecked = new Date().toISOString();

But here’s the important bit: the cache is only cleared when it should be.

If you edit notes or keywords, nothing is invalidated.

If you change the domain name or host list, the cache is wiped:

if (nameChanged || hostsChanged) {
  dom.cache = {};
}

That one small decision makes the tool feel calm instead of twitchy.

What this tool is not

It is not:

an auto-discovery system
a real-time monitor
a source of legal truth about domain ownership

It assumes:

you know which domains you own
you know which hosts matter
you’ll refresh things when you care

In return, it stays small, fast, and understandable.

Possible future improvements (and non-improvements)

Things I might add:

more provider heuristics (DigitalOcean, Fly.io, etc.)
configurable IP allow-lists per provider
better handling of registrar quirks per TLD
bulk refresh with throttling

Things I probably won’t:

accounts
sync
background polling
turning this into a product

The moment it needs a backend, it stops being this tool.

Why I’m happy with it

This started as a way to get a handle on my own past enthusiasm for buying domains.

It ended up as a reminder that:

a browser is a perfectly good runtime
not every problem needs infrastructure
“good enough and honest” beats “comprehensive but fragile”

If you own more domains than you’d like to admit, you might find it useful too.

And if nothing else, it’s a nice excuse to build something small, tidy, and under your control.

App::HTTPThis: the tiny web server I keep reaching for

Dave Cross — Sun, 04 Jan 2026 13:46:13 +0000

Whenever I’m building a static website, I almost never start by reaching for Apache, nginx, Docker, or anything that feels like “proper infrastructure”. Nine times out of ten I just want a directory served over HTTP so I can click around, test routes, check assets, and see what happens in a real browser.

For that job, I’ve been using App::HTTPThis for years.

It’s a simple local web server you run from the command line. Point it at a directory, and it serves it. That’s it. No vhosts. No config bureaucracy. No “why is this module not enabled”. Just: run a command and you’ve got a website.

Why I’ve used it for years

Static sites are deceptively simple… right up until they aren’t.

You want to check that relative links behave the way you think they do.
You want to confirm your CSS and images are loading with the paths you expect.
You want to reproduce “real HTTP” behaviour (caching headers, MIME types, directory handling) rather than viewing files directly from disk.

Sure, you can open file:///.../index.html in a browser, but that’s not the same thing as serving it over HTTP. And setting up Apache (or friends) feels like bringing a cement mixer to butter some toast.

With http_this, the workflow is basically:

cd into your site directory
run a single command
open a URL
get on with your life

It’s the “tiny screwdriver” that’s always on my desk.

Why I took it over

A couple of years ago, the original maintainer had (entirely reasonably!) become too busy elsewhere and the distribution wasn’t getting attention. That happens. Open source is like that.

But I was using App::HTTPThis regularly, and I had one small-but-annoying itch: when you visited a directory URL, it would always show a directory listing - even if that directory contained an index.html. So instead of behaving like a typical web server (serve index.html by default), it treated index.html as just another file you had to click.

That’s exactly the sort of thing you notice when you’re using a tool every day, and it was irritating enough that I volunteered to take over maintenance.

(If you want to read more on this story, I wrote a couple of blog posts.)

What I’ve done since taking it over

Most of the changes are about making the “serve a directory” experience smoother, without turning it into a kitchen-sink web server.

1) Serve index pages by default (autoindex)

The first change was to make directory URLs behave like you’d expect: if index.html exists, serve it automatically. If it doesn’t, you still get a directory listing.

2) Prettier index pages

Once autoindex was in place, I then turned my attention to the fallback directory listing page. If there isn’t an index.html, you still need a useful listing — but it doesn’t have to look like it fell out of 1998. So I cleaned up the listing output and made it a bit nicer to read when you do end up browsing raw directories.

3) A config file

Once you’ve used a tool for a while, you start to realise you run it the same way most of the time.

A config file lets you keep your common preferences in one place instead of re-typing options. It keeps the “one command” feel, but gives you repeatability when you want it.

4) `--host` option

The ability to control the host binding sounds like an edge case until it isn’t.

Sometimes you want:

only localhost access for safety;
access from other devices on your network (phone/tablet testing);
behaviour that matches a particular environment.

A --host option gives you that control without adding complexity to the default case.

The Bonjour feature (and what it’s for)

This is the part I only really appreciated recently: App::HTTPThis can advertise itself on your local network using mDNS / DNS-SD – commonly called Bonjour on Apple platforms, Avahi on Linux, and various other names depending on who you’re talking to.

It’s switched on with the --name option.

http_this --name MyService

When you do that, http_this publishes an _http._tcp service on your local network with the instance name you chose (MyService in this case). Any device on the same network that understands mDNS/DNS-SD can then discover it and resolve it to an address and port, without you having to tell anyone, “go to http://192.168.1.23:7007/”.

Confession time: I ignored this feature for ages because I’d mentally filed it under “Apple-only magic” (Bonjour! very shiny! probably proprietary!). It turns out it’s not Apple-only at all; it’s a set of standard networking technologies that are supported on pretty much everything, just under a frankly ridiculous number of different names. So: not Apple magic , just local-network service discovery with a branding problem.

Because I’d never really used it, I finally sat down and tested it properly after someone emailed me about it last week, and it worked nicely, nicely enough that I’ve now added a BONJOUR.md file to the repo with a practical explanation of what’s going on, how to enable it, and a few ways to browse/discover the advertised service.

(If you’re curious, look for _http._tcp and your chosen service name.)

It’s a neat quality-of-life feature if you’re doing cross-device testing or helping someone else on the same network reach what you’re running.

Related tools in the same family

App::HTTPThis is part of a little ecosystem of “run a thing here quickly” command-line apps. If you like the shape of http_this, you might also want to look at these siblings:

https_this : like http_this, but served over HTTPS (useful when you need to test secure contexts, service workers, APIs that require HTTPS, etc.)
cgi_this : for quick CGI-style testing without setting up a full web server stack
dav_this : serves content over WebDAV (handy for testing clients or workflows that expect DAV)
ftp_this : quick FTP server for those rare-but-real moments when you need one

They all share the same basic philosophy: remove the friction between “I have a directory” and “I want to interact with it like a service”.

Wrapping up

I like tools that do one job, do it well, and get out of the way. App::HTTPThis has been that tool for me for years and it’s been fun (and useful) to nudge it forward as a maintainer.

If you’re doing any kind of static site work — docs sites, little prototypes, generated output, local previews — it’s worth keeping in your toolbox.

And if you’ve got ideas, bug reports, or platform notes (especially around Bonjour/Avahi weirdness), I’m always happy to hear them.

The post App::HTTPThis: the tiny web server I keep reaching for first appeared on Perl Hacks.