@deadair/plugin-sdk 0.86.0 → 0.86.1

package/dist/feed.parse.d.ts

@@ -18,10 +18,16 @@ import type { HostFetchInit, PluginHost } from './plugin.host.js';
  * thin deliberately: `host.fetch` already carries the allowlist, the pacing and
  * the `Retry-After` back-off, so there is nothing left here but a status check.
  *
- * Caching and conditional GET (`ETag`, `Last-Modified`) are NOT here. They
- * belong to whoever is polling — a plugin knows how often its own feeds are
- * worth asking and this file does not — and putting a cache behind a pure
- * parser would hide it from the one caller that must not be surprised by it.
+ * Caching is NOT here: how often a feed is worth asking belongs to whoever is
+ * polling, and a plugin knows that about its own feeds where this file does
+ * not. Conditional GET IS here, because it is not a cache in the sense that
+ * matters. {@link fetchFeed} remembers the `ETag` and `Last-Modified` the
+ * publisher sent with the last document it parsed for a URL, sends them back
+ * as `If-None-Match` and `If-Modified-Since`, and answers a 304 with that
+ * document. Every call still goes on the wire and the publisher still decides
+ * whether anything changed, so no caller can be handed a stale feed by it;
+ * what an unchanged feed costs becomes a status line instead of a document.
+ * See {@link FEED_VALIDATORS_MAX} for the bound.
  *
  * ## A podcast is a feed with an attachment
  *
@@ -176,6 +182,21 @@ export declare function parseFeed(xml: string): ParsedFeed;
  * neighbours — which {@link PluginErrorCode} a status means — and that is
  * `plugin.http.ts`'s ladder, unmodified. A service with its own reading of a
  * status layers that in front by calling {@link parseFeed} itself.
+ *
+ * The one thing it adds to the request is conditional GET: the validators the
+ * publisher sent last time go back with this request, and a 304 is answered
+ * with the document they came from (a copy, so a caller that edits what it was
+ * handed cannot edit what the next caller gets). A 304 this did not ask for is
+ * the caller's own and fails the status check like any other non-2xx.
  */
 export declare function fetchFeed(host: PluginHost, url: string, init?: HostFetchInit): Promise<ParsedFeed>;
+/**
+ * How many feeds one host remembers validators for, oldest dropped first.
+ *
+ * A station reads tens of feeds rather than thousands, so this is a ceiling a
+ * plugin that builds URLs from user input cannot grow past rather than a size
+ * anybody is expected to reach. Losing an entry costs one full document the
+ * next time that feed is asked, and nothing else.
+ */
+export declare const FEED_VALIDATORS_MAX = 256;
 //# sourceMappingURL=feed.parse.d.ts.map

package/dist/feed.parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feed.parse.d.ts","sourceRoot":"","sources":["../src/feed.parse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACrB;;;;;;;;;;;;OAYG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,KAAK,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAuB1C;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAqDjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBxG"}
+{"version":3,"file":"feed.parse.d.ts","sourceRoot":"","sources":["../src/feed.parse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACrB;;;;;;;;;;;;OAYG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,KAAK,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAuB1C;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAqDjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAiCxG;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/index.js

@@ -786,7 +786,16 @@ function parseFeed(xml) {
 }
 __name(parseFeed, "parseFeed");
 async function fetchFeed(host, url, init) {
-  const response = await host.fetch(url, init);
+  const known = validatorsFor(host);
+  const remembered = known.get(url);
+  const asked = conditional(init, remembered);
+  const response = await host.fetch(url, asked ?? init);
+  if (response.status === 304 && remembered !== void 0 && asked !== void 0) {
+    await response.body?.cancel();
+    known.delete(url);
+    known.set(url, remembered);
+    return structuredClone(remembered.feed);
+  }
   if (!response.ok) {
     await response.body?.cancel();
     const error = new PluginError(`feed request failed: ${upstreamDetail(response.status, response.statusText)}`).withCode(pluginCodeForStatus(response.status));
@@ -795,9 +804,54 @@ async function fetchFeed(host, url, init) {
     if (advice !== void 0) error.withRetry(advice);
     throw error;
   }
-  return parseFeed(await response.text());
+  const feed = parseFeed(await response.text());
+  remember(known, url, response.headers, feed);
+  return feed;
 }
 __name(fetchFeed, "fetchFeed");
+var FEED_VALIDATORS_MAX = 256;
+var validatorsByHost = /* @__PURE__ */ new WeakMap();
+function validatorsFor(host) {
+  let known = validatorsByHost.get(host);
+  if (known === void 0) {
+    known = /* @__PURE__ */ new Map();
+    validatorsByHost.set(host, known);
+  }
+  return known;
+}
+__name(validatorsFor, "validatorsFor");
+function conditional(init, remembered) {
+  if (remembered === void 0) return void 0;
+  const headers = {
+    ...init?.headers
+  };
+  const named = new Set(Object.keys(headers).map((name) => name.toLowerCase()));
+  if (named.has("if-none-match") || named.has("if-modified-since")) return void 0;
+  if (remembered.etag !== void 0) headers["if-none-match"] = remembered.etag;
+  if (remembered.lastModified !== void 0) headers["if-modified-since"] = remembered.lastModified;
+  return {
+    ...init,
+    headers
+  };
+}
+__name(conditional, "conditional");
+function remember(known, url, headers, feed) {
+  known.delete(url);
+  const etag = headers.get("etag") ?? void 0;
+  const lastModified = headers.get("last-modified") ?? void 0;
+  if (etag === void 0 && lastModified === void 0) return;
+  const entry = {
+    feed: structuredClone(feed)
+  };
+  if (etag !== void 0) entry.etag = etag;
+  if (lastModified !== void 0) entry.lastModified = lastModified;
+  known.set(url, entry);
+  if (known.size > FEED_VALIDATORS_MAX) {
+    const oldest = known.keys().next().value;
+    if (oldest !== void 0) known.delete(oldest);
+  }
+}
+__name(remember, "remember");
 function readItem(entry) {
   const title = speakable(entry.title);
   if (title === void 0) return void 0;
@@ -1565,6 +1619,7 @@ export {
   ENRICHMENT_MATCH_KEY_ARTIST_TITLE,
   ENRICHMENT_MATCH_KEY_ISRC,
   FEED_SUMMARY_MAX_CHARS,
+  FEED_VALIDATORS_MAX,
   HOST_FETCH_METHODS,
   JSON_SAFE_PAYLOAD_TYPES,
   KNOWN_ENRICHMENT_MATCH_KEYS,