Webring & Atom Feeds

Relevant source files

The following files were used as context for generating this wiki page:

• PLAN.md
• src/server.js
• src/views.js
• src/widgets.js
• test/app.test.js
• src/util.js

PuppyPad implements community discovery and syndication features through a Webring system and Atom-formatted activity feeds. The Webring connects member sites in a navigable chain, while Atom feeds provide machine-readable updates for individual sites and the global platform.

Webring System

The Webring is an opt-in discovery system that allows visitors to navigate between participating PuppyPad sites. It utilizes specific database flags and routing logic to maintain a circular navigation path.

Opt-in Logic and Requirements

A site appears in the webring only if it meets specific criteria to ensure quality and prevent spam. The member must explicitly join via the dashboard.

• Opt-in Status: The users.webring database column must be set to 1.
• Listing Requirements: The site must be verified, not banned, and not hidden.
• Activity Threshold: The site must have at least one update (updates > 0).
• Cooldown Period: The site must be older than the NEW_SITE_HOURS configuration (default 24 hours).

Sources: src/server.js:127-129, src/server.js:527-528, PLAN.md:162-164

Webring Navigation Logic

Navigation is handled by three primary routes: /webring/prev, /webring/next, and /webring/random. The system uses the id column to determine the "previous" and "next" members, wrapping around to the start or end of the list when the boundary is reached.

Webring Integration Table

Route	Logic	Description
/webring/next	ID > current	Redirects to the next site in the ring based on incremental ID.
/webring/prev	ID < current	Redirects to the previous site in the ring.
/webring/random	ORDER BY RANDOM()	Redirects to a random participating site.
/random	ORDER BY RANDOM()	Redirects to any listed site, regardless of webring status.

Sources: src/server.js:527-545

Atom Feeds

PuppyPad generates Atom feeds to allow users and external applications to subscribe to site updates. The system provides both a global feed and individual site feeds.

Feed Generation

The application uses the events table to track site updates. Every save or upload operation that modifies files triggers an update event, which captures the modified file names.

Feed Types

1. Global Feed (/feed.xml): Aggregates recent update events from all listed (verified, unbanned, unhidden) sites. It excludes join events.
2. Site Feed (/site/:name/feed.xml): Contains all events (updates and joins) specific to a single member site.

Sources: src/server.js:513-526

Data Structure for Feeds

The V.atom view helper constructs the XML structure using the following mapping:

Atom Field	Source Data	Description
<title>	username + eventText	Descriptive title of the update.
<id>	tag:BASE_HOST,2026:event-ID	Unique identifier for the feed entry.
<updated>	created_at	ISO timestamp of the event.
<content>	fileLinks	HTML links to the modified files.

Sources: src/views.js:560-571, src/server.js:82-96

Syndication Widgets

Members add webring and feed functionality to their sites using HTML snippets provided in the dashboard.

• Webring Bar: A snippet containing links to the prev, random, and next routes.
• Atom Link: Templates include <link rel="alternate"> tags in the <head> to allow browsers and feed readers to auto-discover site feeds.
• Last Updated Badge: An SVG widget (/_hw/updated.svg) that dynamically displays the site's updated_at timestamp.

Sources: src/widgets.js:58-59, src/views.js:106-112, templates/notebook.html:73-77

Automated Notification Logic

The syndication system extends to email through the Housekeeping service.

Weekly Digest

The system sends a weekly email to members who opt-in (users.digest = 1). This email summarizes updates from sites the member follows. The service runs every hour, selecting users whose digest_at is older than 7 days.

Implementation Summary

The combination of the Webring and Atom feeds creates a decentralized discovery network. The Webring facilitates manual browsing ("surfing"), while Atom feeds facilitate automated monitoring. Both systems rely on the events table for activity data and the users table for visibility flags.

Sources: PLAN.md:162-166, src/server.js:513-545