Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,44 @@ Updating is changing the image tag and redeploying. The database migrates itself
forward on start, and no release so far has needed anything else — where a release
changes what your listeners see, it says so.

## Unreleased

### Fixed — the statistics said more than had happened

- **A HEAD request was counted as a download of the whole file.** Overcast, Apple's crawler
and every feed validator ask for an episode's headers before fetching it, and SelfPod
recorded each of those as a completed download carrying the file's full size as "sent" —
while nothing had left the server. Two header checks on a 29 MB episode put 56 MB on the
Audio served card. A HEAD is no longer recorded at all.
- **A 304 was counted as a download.** A browser or an iPhone revalidating a cached episode
is answered "not modified" with no body; that reply was a download in every figure. It is
now in the log as a 304 that sent nothing, and in no total.
- **A download the app gave up on was counted as one it received.** The log already knew the
app had disconnected — it said so in the row — but the row kept its green 200, the
Downloads card counted it, and the CSV called it "ok". It is now shown as *partial*,
exported as `partial`, and counted nowhere. A stream the player stopped part-way through
is still a stream: that is how players behave.
- **Apple Podcasts never registered a download.** It fetches every episode with
`Range: bytes=0-` and is answered with the whole file; the presence of the range made it a
stream. A range from byte zero that delivers the entire file is now a download, whichever
app asked. The two-byte probe an iPhone sends first stays a stream.
- **"AppleCoreMedia" is no longer credited to Apple Podcasts.** It is the system player on an
iPhone, iPad or Mac, and it speaks for whichever app is streaming through it — Overcast,
Castro and Safari included. The chart now calls it "Apple media player", and the page says
what that means.
- **The Audio served card compared bytes as a bare number** ("+58,963,151 vs the previous 30
days"). It now says "+56.2 MB".
- A resumed download answered with the whole file (an address from an earlier cut) lost the
range it had asked for before the row was written, so the log could not show why. The range
is kept.

### Changed

- Dependencies brought up to patched releases: Fastify 5.12.5 (seven advisories, including an
authentication bypass through malformed URLs and X-Forwarded header spoofing), sharp 0.35.5
(libheif and librsvg), music-metadata 11.16.1 (crafted MP4, EBML and DSF files could crash
the scanner — and the scanner reads whatever is dropped on the share). `npm audit` is clean.

## 1.9.1 — 2026-09-16

### Fixed
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ regenerate button.
and partial streams are counted separately, alongside a request-by-request log
naming the app that asked (“Pocket Casts”, “Apple Podcasts”). Failed requests
are shown first, so an episode that will not download in someone's podcast app
is visible here instead of only on their phone. No IP addresses are stored, and
is visible here instead of only on their phone, and a download the app gave up
on is listed as partial rather than counted. No IP addresses are stored, and
your own visits to the admin interface are never counted.
- **Tells you when something is wrong.** Every scan is logged in plain language —
a permission problem names the exact path and the UID SelfPod runs as. You
Expand Down
184 changes: 184 additions & 0 deletions doc/audit-2026-10-09.md

Large diffs are not rendered by default.

310 changes: 155 additions & 155 deletions package-lock.json

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "selfpod",
"version": "1.9.1",
"description": "SelfPod \u2014 a self-hosted podcast server. Drop a file in a folder; it's an episode.",
"description": "SelfPod — a self-hosted podcast server. Drop a file in a folder; it's an episode.",
"license": "MIT",
"type": "module",
"private": false,
Expand Down Expand Up @@ -29,14 +29,14 @@
"better-sqlite3": "13.0.3",
"chokidar": "4.0.3",
"eta": "4.6.0",
"fastify": "5.11.3",
"fastify": "5.12.5",
"fastify-plugin": "6.0.0",
"htmlparser2": "12.0.0",
"mpg123-decoder": "1.0.3",
"music-metadata": "11.14.0",
"music-metadata": "11.16.1",
"pino": "10.3.1",
"qrcode": "1.5.4",
"sharp": "0.35.3",
"sharp": "0.35.5",
"xmlbuilder2": "4.0.3"
},
"devDependencies": {
Expand Down
86 changes: 68 additions & 18 deletions src/routes/public.js
Original file line number Diff line number Diff line change
Expand Up @@ -51,37 +51,83 @@ export default async function publicRoutes(fastify, { config, settings, shows, e
* however many times those events arrive.
*/
function trackAccess(request, reply, extra) {
if (isOwnRequest(request)) return;
if (!worthRecording(request)) return;
let done = false;
const settle = (aborted) => {
if (done) return;
done = true;
const statusCode = reply.statusCode;
// On an abort the Content-Length header describes what was promised, not
// what arrived, so claiming it as "sent" would be a lie. A 304 is the opposite
// case — a response that completed and deliberately carried no body — so it
// is a zero whoever sent it. `??` and not `||`, because `0 || null` is null,
// and recording a zero that is a fact as the null that means "unknowable" is
// the very confusion this line exists to avoid.
const bytesSent = aborted
? null
: statusCode === 304
? 0
: (extra.bytesSent ?? (Number(reply.getHeader('content-length')) || null));
const totalBytes = extra.totalBytes ?? null;
// The range as the client sent it, even when the handler then chose to ignore
// it: a resumed download that was answered with the whole file is only
// explicable in the log if the range it asked for is still there.
const rangeHeader = extra.rangeHeader ?? request.headers.range ?? null;
stats?.record({
kind: extra.kind,
kind: mediaKind(extra.kind, { rangeHeader, statusCode, bytesSent, totalBytes }),
episodeId: extra.episodeId ?? null,
showId: extra.showId ?? null,
statusCode: reply.statusCode,
// On an abort the Content-Length header describes what was promised, not
// what arrived, so claiming it as "sent" would be a lie. A 304 is the opposite
// case — a response that completed and deliberately carried no body — so its
// caller states the zero. `??` and not `||`, because `0 || null` is null, and
// recording a zero that is a fact as the null that means "unknowable" is the
// very confusion this line exists to avoid.
bytesSent: aborted
? null
: (extra.bytesSent ?? (Number(reply.getHeader('content-length')) || null)),
totalBytes: extra.totalBytes ?? null,
rangeHeader: request.headers.range ?? null,
statusCode,
bytesSent,
totalBytes,
rangeHeader,
userAgent: request.headers['user-agent'] ?? null,
error: aborted
? 'The app disconnected before the transfer finished, so this download is incomplete.'
: (extra.error ?? explainFailure(reply.statusCode, extra)),
: (extra.error ?? explainFailure(statusCode, extra)),
});
};
reply.raw.once('finish', () => settle(false));
reply.raw.once('close', () => settle(!reply.raw.writableFinished));
}

/**
* Whether a request belongs in the access log at all.
*
* Not the owner's own session, and not a HEAD. Fastify answers HEAD with the
* same handler as GET, so a HEAD used to be recorded as a download carrying the
* file's whole size as "bytes sent" — while nothing left the server. Overcast,
* Apple's crawler and every feed validator HEAD an enclosure before fetching it,
* which was enough to double some episodes' figures.
*/
function worthRecording(request) {
return request.method !== 'HEAD' && !isOwnRequest(request);
}

/**
* Download or stream, decided from what was actually served rather than from the
* mere presence of a Range header.
*
* Apple Podcasts asks for every file with `Range: bytes=0-` and is answered with
* a 206 carrying the whole thing; counting that as a stream meant the most common
* podcast app on iPhones never registered a download. So: no range, an open-ended
* range from byte zero, or a 206 whose body was the entire file is a download. A
* range that starts mid-file, or a bounded one short of the end, is a player
* buffering or seeking — a stream. Feed and cover kinds pass through untouched.
*/
function mediaKind(kind, { rangeHeader, statusCode, bytesSent, totalBytes }) {
if (kind !== ACCESS_KIND.DOWNLOAD && kind !== ACCESS_KIND.STREAM) return kind;
// A 200 is the whole representation by definition, whatever range was asked for —
// the answer a resuming client gets when its address is from an earlier cut.
if (statusCode === 200) return ACCESS_KIND.DOWNLOAD;
const range = String(rangeHeader ?? '').trim();
if (range === '' || /^bytes=0-$/.test(range)) return ACCESS_KIND.DOWNLOAD;
if (statusCode === 206 && totalBytes > 0 && bytesSent !== null && bytesSent >= totalBytes) {
return ACCESS_KIND.DOWNLOAD;
}
return ACCESS_KIND.STREAM;
}

/**
* A sentence for a failure nobody explained.
*
Expand Down Expand Up @@ -519,7 +565,7 @@ export default async function publicRoutes(fastify, { config, settings, shows, e
*/
const refuse = (error, code) => {
request.log.warn({ file: serving.filename, show: show.slug, code }, error);
if (!isOwnRequest(request)) {
if (worthRecording(request)) {
stats?.record({
kind: ACCESS_KIND.DOWNLOAD,
episodeId: episode.id,
Expand Down Expand Up @@ -616,9 +662,13 @@ export default async function publicRoutes(fastify, { config, settings, shows, e
// A range request is a player streaming or seeking; a plain GET is an app
// fetching the episode for offline listening. They are counted separately
// because conflating them makes the download figure meaningless.
const kind = request.headers.range ? ACCESS_KIND.STREAM : ACCESS_KIND.DOWNLOAD;
// Whether this ends up a download or a stream is settled once the response has
// finished (see mediaKind): a range from byte zero that delivered the whole file
// is a download, whatever the header said. The range is passed explicitly
// because a whole-file answer to a stale address deletes it from the request.
trackAccess(request, reply, {
kind,
kind: request.headers.range ? ACCESS_KIND.STREAM : ACCESS_KIND.DOWNLOAD,
rangeHeader: range || null,
episodeId: episode.id,
showId: show.id,
totalBytes: fileStats.size,
Expand Down
Loading
Loading