PodcastFeedVapor

PodcastFeedMaker can generate, parse, validate, and audit podcast RSS feeds. Great. But once you have your clean XML… you still need to serve it somewhere.

On a client project, I needed feeds generated on-the-fly from a database — no static files, no CDN, real RSS built at HTTP request time. I started with a naive Vapor handler: build the feed, serialize, return the response. It worked, but without ETag, without Cache-Control, without CORS, without any of what a production RSS feed really requires.

Rather than reinventing these building blocks on every project, I extracted everything into a separate lib. PodcastFeedVapor was born from this concrete need: turn any Vapor app into a podcast server, with everything properly handled on the HTTP side, while keeping a strict separation between what's reusable (the open-source lib) and what's business logic (your app).

It's a middleware layer for Vapor that sits between your business logic and the HTTP client. Basically: you build a PodcastFeed with PodcastFeedMaker's DSL, and PodcastFeedVapor handles the rest — headers, caching, CORS, streaming, pagination.

The whole thing is split into four Swift Package Manager targets. You import only what you need, nothing more.

Here's everything you need for a Vapor app to serve a podcast RSS feed with HTTP caching, CORS, and a custom generation header. No magic, just configuration:

A GET /feed.xml returns XML with Content-Type: application/rss+xml, a SHA256 ETag, a Cache-Control: public, max-age=3600, a Last-Modified, and an X-Generator: MyApp/1.0 header. 200 OK the first time, then 304 Not Modified if the content hasn't changed. Exactly what you'd expect from a production feed.

Three middlewares cover the classic HTTP needs of a production RSS feed. They stack in a specific order — CORS first (outermost), then cache, then the generation header (innermost). Each only touches RSS responses and silently ignores the rest. Your JSON API keeps working normally.

Adds a configurable X-Generator header on each RSS response. Useful for debugging, monitoring, and especially for identifying which server produced a feed in a distributed environment. Non-RSS responses (JSON, HTML, etc.) pass through unchanged — the middleware detects the Content-Type and only acts on application/rss+xml.

Handles conditional HTTP caching. On each RSS response, it computes a SHA256 hash of the body and attaches it as an ETag. If the client sends back that tag in an If-None-Match, and the content hasn't changed, the middleware short-circuits the response with a 304 Not Modified — zero body, zero generation work on the server.

It also adds a Last-Modified (generation date) and a Cache-Control: public, max-age=N configurable via CacheControlDuration — in minutes, hours, or seconds depending on your needs.

Full CORS with OPTIONS preflight handling. By default, it allows all origins (*) with a max-age of 86400 seconds. You can restrict to a specific origin if your use case requires it. Preflight returns a 204 No Content with no body — exactly what a modern browser expects.

podcastFeed() is an extension on Application and RoutesBuilder that registers a GET with automatic PodcastFeed to XML encoding. It supports static paths and dynamic parameters, exactly like the Vapor routes you already know.

Internally, FeedResponseEncoder converts the PodcastFeed to a Response with the right Content-Type, pretty-print if configured, and hands off to middlewares for HTTP headers. If you prefer full control, req.feedResponse(feed) and Response.xml("...") are also available.

For a podcast with 500 episodes, serving all 500 on every request makes no sense. FeedPagination extracts limit and offset parameters from the query string and clamps them within reasonable bounds. No accidental limit of 10,000, no negative offset that would crash your SQL query.

For truly massive catalogs where even pagination isn't enough, StreamingFeedResponse generates XML in chunks and streams it via Transfer-Encoding: chunked — the server never needs to hold the entire feed in memory. Perfect for platforms hosting thousands of episodes.

Three pure Swift protocols transform your types into feeds. Note: these are not Fluent protocols — they work with any type, struct or class. It's just a simple contract: you implement a to*() method, and the lib knows how to convert.

When you publish an episode, aggregators don't continuously check your feed — they wait for a signal. Podping is that signal. PodpingNotifier sends an HTTP POST webhook to alert the ecosystem that a feed has changed. Simple, effective.

Batch audit exposes an endpoint that scores multiple feeds in parallel via PodcastFeedMaker's FeedAuditor. Just pass the URLs in the query string — each feed is fetched, parsed, analyzed, and graded. Handy for monitoring an entire catalog's quality.

The JSON response contains the score (0-100), letter grade (A to F), and number of recommendations for each feed. We tested with real production feeds during development — a Simplecast got a D/68 with 9 recommendations, a Megaphone returning HTML instead of RSS logically got an F/0. Real-world results.

PodcastFeedVapor's core has no dependency on Redis or Vapor Queues. Two optional targets add these capabilities for deployments that actually need them.

FeedCacheStore defines a simple contract: store, retrieve, invalidate. The Redis implementation uses SETEX (set with expiry) and SCAN for pattern invalidation. It plugs in with one line in your config:

For heavy feeds or scheduled regenerations, FeedRegenerationJob integrates with Vapor Queues. You implement a handler, register it, and you can dispatch regeneration jobs from any route handler.

The 0.1.0 XML streaming solved the memory problem on large catalogs. But each request regenerated the feed from scratch. StreamingCacheResponse combines both: XML is streamed to the client AND cached simultaneously. The first request generates and stores, subsequent ones are served from cache with a SHA256 ETag.

FeedCacheStore is a protocol — you plug in whatever backend you want. InMemoryFeedCache is provided for dev and tests, RedisFeedCache for production.

First request: Transfer-Encoding: chunked, no ETag — XML is generated and streamed in real-time. Second request: fixed Content-Length, SHA256 ETag, served from cache. The client can then send an If-None-Match to get a 304.

The PodcastFeedVaporMetrics target builds on Apple's swift-metrics — backend-agnostic, you plug in Prometheus, StatsD, Datadog, or any compatible collector. FeedMetricsMiddleware goes first in the middleware stack and automatically records every feed request.

The pfv_ prefix is configurable via FeedMetricsConfiguration. The active streams gauge is a dedicated actor (FeedActiveStreamsGauge) that increments when a stream starts and decrements when it ends — no locks, no race conditions.

0.1.0 had PodpingNotifier for outgoing HTTP webhooks. 0.2.0 adds an incoming WebSocket channel: clients connect, subscribe to specific feeds, and receive push notifications when a feed is updated. Both mechanisms coexist — webhook for notifying aggregators, WebSocket for notifying your own clients.

On the client side, communication uses JSON with 5 message types: welcome on connection, subscribe/unsubscribe for filtering, subscribed as confirmation, and notification for updates. A client without filters receives everything; a subscribed client only gets the feeds they care about.

During development, we built a complete test server to validate each feature with real HTTP calls. The repo includes a script that automatically generates it as a standalone Vapor project — handy for seeing how everything fits together.

The server exposes 11 endpoints covering all lib features: static feed, rich feed with Podcast NS 2.0 metadata, dynamic feed with pagination, batch audit, health check, CORS preflight, streaming cache with ETag, real-time WebSocket Podping, and swift-metrics.

Every feature was tested with curl against a real Vapor server running locally. 24 scenarios total — 12 static checks and 12 live functional tests including streaming cache, WebSocket Podping, and metrics. When we say it works, it's because we actually ran it.

An architecture detail worth mentioning: in the sample server, feed construction (Feeds.swift) is separated from the Vapor entry point (App.swift). Why? A naming conflict between PodcastFeedMaker's Channel and NIO's Channel (Vapor's network runtime). By keeping imports separate, the compiler resolves types unambiguously. It's documented in the project because every developer mixing both imports will run into this sooner or later.

282 tests across 55 suites on 4 targets. Overall coverage of 93.85% — up +3.6% from 0.1.0. Core reaches 99%+, queues 98.1%. Redis is lower (27.3%) because integration tests require a real Redis server, but the FeedCacheStore protocol is fully tested via a mock.

Each feature has showcase tests that also serve as executable documentation. The code examples in DocC and in this article come from these tests — what's written here has been compiled and executed.

Four products are available. Import the core, and add Redis, Queues, or Metrics only if your deployment actually uses them:

The specs PodcastFeedVapor builds on, via PodcastFeedMaker: