How We Built Permanent URLs for Tool Distribution

When we set out to build get.tool, we had one core requirement: URLs must be permanent. Once a file is published at a specific version, that URL should work forever. This is harder than it sounds.

In this post, we'll explore the architecture decisions that make permanent URLs possible, the trade-offs we made, and lessons learned along the way.

The Problem with Mutable URLs

Most package registries treat versions as mutable. You can publish version 1.0.0, then unpublish it, or worse, republish with different content. This breaks a fundamental promise: that a specific version points to specific content.

For scripts that run directly from URLs, this is dangerous. Imagine embedding a script in your documentation:

<script src="https://example.com/lib@1.0.0/script.js"></script>

If the content at that URL can change, you have no way to ensure your users see consistent behavior. Worse, if the URL goes away entirely, your documentation breaks.

Our Approach: Immutable Versions

Every version in get.tool is immutable once published. The storage layer enforces this at the infrastructure level, not just the application level. Here's how it works:

// Simplified version of our storage architecture
const storage = {
  async publish(tool, version, files) {
    const key = `${tool}/@${version}`;

    // Check if version already exists
    if (await this.exists(key)) {
      throw new Error('Version already exists');
    }

    // Write files with immutable flag
    await this.writeImmutable(key, files);

    // Update @latest pointer (this IS mutable)
    await this.updatePointer(tool, 'latest', version);
  }
};

The @latest Pointer

We make one exception to immutability: the @latest tag. This is explicitly a mutable pointer that always points to the most recent version. Users who want stability should pin to a specific version; users who want automatic updates use @latest.

Integrity Verification with SRI

Permanent URLs are only useful if you can verify the content hasn't been tampered with. We generate Subresource Integrity (SRI) hashes for every file:

<script
  src="https://get.tool.ab0t.com/p/my-tool/@1.0.0/script.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
  crossorigin="anonymous"
></script>

Browsers automatically verify the hash before executing the script. If someone manages to modify the content, the script simply won't run.

Storage Architecture

Our storage layer is designed for permanence:

• Object storage with versioning enabled and deletion disabled
• Multi-region replication for durability
• CDN caching with immutable cache headers
• Backup rotation with long retention periods

"The best way to ensure URLs never break is to make it technically impossible to break them."

What About Deletions?

Sometimes you need to remove content. Maybe you accidentally published credentials, or there's a legal requirement. We handle this with tombstones:

1. The original content is removed from CDN and public access
2. A tombstone file is placed at the URL explaining the removal
3. The URL continues to resolve (returns 410 Gone, not 404)
4. SRI hashes are preserved for audit purposes

This maintains the promise that URLs don't break, while still allowing necessary removals.

Lessons Learned

Building for permanence changes how you think about infrastructure:

1. Design for failure

Everything fails eventually. Design systems that fail gracefully and preserve data across failures.

2. Immutability simplifies everything

When content can't change, caching is trivial, replication is safe, and debugging is straightforward.

3. Be explicit about mutability

Our @latest pointer is intentionally obvious. Users know it's mutable by convention.

---

Permanent URLs are a commitment. Once you promise them, you can't take them back. But that commitment is exactly what makes the system trustworthy.

Want to try it out? Create an account and publish your first tool.