@jant/core 0.6.15 → 0.7.0

package/src/routes/discover-announce.ts

@@ -0,0 +1,96 @@
+/**
+ * Announcing a site to its directory, from whichever route just gave it a
+ * reason to.
+ *
+ * Two routes have one: the settings page, whenever the owner turns Discover on
+ * or off, and first-run setup, when they answer the same question for the first
+ * time. Both send the same thing to the same place, so they send it through the
+ * same function rather than through two that drift.
+ *
+ * The transport lives in `lib/discover-ping.ts` and the protocol in
+ * `lib/discover.ts`. What is here is the part that needs a request: the
+ * deployment's endpoint, the site's own address, and the runtime's hook for
+ * work that outlives the response.
+ */
+
+import type { Context } from "hono";
+import type { Bindings } from "../types.js";
+import type { AppVariables } from "../types/app-context.js";
+import { runDeferred } from "../lib/deferred.js";
+import {
+  getDiscoverFeedPath,
+  parseDiscoverSetting,
+  resolveDiscoverMode,
+} from "../lib/discover.js";
+import { getDiscoverDefault, getDiscoverPingUrl } from "../lib/env.js";
+import { toAbsoluteSiteUrl } from "../lib/url.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+/**
+ * Tell the configured directory where this site's feed is, in the background.
+ *
+ * Never awaited by its caller. A directory takes up to twelve seconds to give
+ * up on, and neither a settings save nor the last screen of setup may hang on
+ * one — nor fail because one is down. The outcome is recorded either way, so
+ * the owner can tell "announced" from "never got through"; the settings page's
+ * status block is where that shows, and it carries a Retry.
+ *
+ * @param c - Request context, for the runtime's background-work hook
+ * @param storedValue - The stored Discover choice. Passed in rather than read
+ *   from `c.var.allSettings`, which is the snapshot taken before the request
+ *   ran — on the save that triggers this it still holds the previous answer.
+ * @returns Whether an announcement was started at all
+ */
+export function announceInBackground(
+  c: Context<Env>,
+  storedValue: string | undefined,
+): boolean {
+  const { appConfig } = c.var;
+  const endpoint = getDiscoverPingUrl(c.env);
+  if (!endpoint) return false;
+
+  // Read the mode back through the same derivation the feed uses, so a site
+  // that cannot actually be polled — feeds switched off, `noindex` set, demo
+  // mode — never announces an address that would answer 404.
+  const mode = resolveDiscoverMode({
+    storedValue,
+    defaultValue: getDiscoverDefault(c.env),
+    demoMode: appConfig.demoMode,
+    noindex: appConfig.noindex,
+    rssFeedsEnabled: appConfig.rssFeedsEnabled,
+  });
+  // A site that has just switched Discover off resolves to `none` and so has
+  // no feed of its own to name — but that is exactly the site with something
+  // to say, and the declaration a directory needs to read sits in every feed,
+  // not only the one it was polling. `/latest/feed` is the address that is
+  // always served, so the stop is sent there.
+  //
+  // Only for an owner's own `off`, never for the other ways a site resolves to
+  // `none`: a demo site or one with feeds switched off would be naming an
+  // address that answers 404.
+  const feedPath =
+    getDiscoverFeedPath(mode) ??
+    (parseDiscoverSetting(storedValue) === "off" &&
+    appConfig.rssFeedsEnabled &&
+    !appConfig.demoMode
+      ? getDiscoverFeedPath("latest")
+      : null);
+  if (!feedPath) return false;
+
+  // Deferred, so the caller answers without waiting on a directory. The helper
+  // is what keeps the orphaned promise from taking a Node process down with
+  // it: `announceToDiscover` already resolves rather than throws, and this is
+  // what holds if it ever stops being.
+  runDeferred(c, "Discover announcement", async () => {
+    await c.var.services.settings.announceToDiscover({
+      endpoint,
+      feedUrl: toAbsoluteSiteUrl(
+        feedPath,
+        appConfig.siteUrl,
+        appConfig.sitePathPrefix,
+      ),
+    });
+  });
+  return true;
+}

package/src/routes/feed/__tests__/feed.test.ts

@@ -6,6 +6,7 @@ import type { AppVariables } from "../../../types/app-context.js";
 import {
   createTestDatabase,
   DEFAULT_TEST_SITE_ID,
+  enforceD1BoundParameterLimit,
 } from "../../../__tests__/helpers/db.js";
 import { posts as postTable } from "../../../db/schema.js";
 import { createPostService } from "../../../services/post.js";
@@ -22,7 +23,7 @@ import type { Database } from "../../../db/index.js";
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
 function createFeedTestApp(envOverrides: Partial<Bindings> = {}) {
-  const { db } = createTestDatabase();
+  const { db, sqlite } = createTestDatabase();
   const pathService = createPathService(db as never, DEFAULT_TEST_SITE_ID);
 
   const services = {
@@ -65,7 +66,12 @@ function createFeedTestApp(envOverrides: Partial<Bindings> = {}) {
   app.route("/latest", latestRoutes);
   app.route("/featured", featuredRoutes);
 
-  return { app, services, db: db as unknown as Database };
+  return { app, services, db: db as unknown as Database, sqlite };
+}
+
+/** Count the `<entry>` elements in an Atom document. */
+function countEntries(xml: string): number {
+  return xml.match(/<entry>/g)?.length ?? 0;
 }
 
 afterEach(() => {
@@ -597,6 +603,132 @@ describe("Atom Feed Routes", () => {
     });
   });
 
+  describe("Discover fields", () => {
+    it("gives every entry the post's own ID beside its permalink id", async () => {
+      const { app, services } = createFeedTestApp();
+      const post = await services.posts.create({
+        format: "note",
+        title: "Identified",
+        bodyMarkdown: "Body",
+        status: "published",
+        slug: "identified",
+      });
+
+      const xml = await (await app.request("/latest/feed")).text();
+
+      expect(xml).toContain(
+        `<id>http://localhost:${DEFAULT_APP_PORT}/identified</id>\n    <jant:id>${post.id}</jant:id>`,
+      );
+    });
+
+    it("names the status endpoint in the declaration while the site is listed", async () => {
+      const { app, services } = createFeedTestApp();
+      await services.settings.set("DISCOVER", "latest");
+
+      const xml = await (await app.request("/latest/feed")).text();
+
+      expect(xml).toContain(
+        ` status="http://localhost:${DEFAULT_APP_PORT}/api/discover/posts">latest</jant:discover>`,
+      );
+    });
+
+    it("names no status endpoint under none", async () => {
+      const { app, services } = createFeedTestApp();
+      await services.settings.set("DISCOVER", "off");
+
+      const xml = await (await app.request("/latest/feed")).text();
+
+      expect(xml).toContain("<jant:discover>none</jant:discover>");
+    });
+  });
+
+  describe("?limit=", () => {
+    async function createNotes(
+      services: ReturnType<typeof createFeedTestApp>["services"],
+      count: number,
+      options: { featured?: boolean } = {},
+    ) {
+      for (let i = 0; i < count; i++) {
+        await services.posts.create({
+          format: "note",
+          title: `Post ${i}`,
+          bodyMarkdown: `Body ${i}`,
+          status: "published",
+          featured: options.featured,
+        });
+      }
+    }
+
+    it("carries more than RSS_FEED_LIMIT when asked", async () => {
+      const { app, services } = createFeedTestApp({ RSS_FEED_LIMIT: "2" });
+      await createNotes(services, 4);
+
+      const xml = await (await app.request("/latest/feed?limit=3")).text();
+
+      expect(countEntries(xml)).toBe(3);
+      expect(xml).toContain("Post 3");
+      expect(xml).toContain("Post 1");
+      expect(xml).not.toContain("Post 0");
+    });
+
+    it("carries fewer when asked", async () => {
+      const { app, services } = createFeedTestApp();
+      await createNotes(services, 3);
+
+      const xml = await (await app.request("/latest/feed?limit=1")).text();
+
+      expect(countEntries(xml)).toBe(1);
+      expect(xml).toContain("Post 2");
+    });
+
+    it("keeps the site's length for a value it cannot read", async () => {
+      const { app, services } = createFeedTestApp({ RSS_FEED_LIMIT: "2" });
+      await createNotes(services, 4);
+
+      for (const query of ["limit=abc", "limit=0", "limit=-1", "limit=1.5"]) {
+        const res = await app.request(`/latest/feed?${query}`);
+        expect(res.status).toBe(200);
+        expect(countEntries(await res.text())).toBe(2);
+      }
+    });
+
+    it("applies to the featured and main feeds", async () => {
+      const { app, services } = createFeedTestApp({ RSS_FEED_LIMIT: "1" });
+      await createNotes(services, 3, { featured: true });
+
+      const featured = await (
+        await app.request("/featured/feed?limit=2")
+      ).text();
+      const main = await (await app.request("/feed?limit=2")).text();
+
+      expect(countEntries(featured)).toBe(2);
+      expect(countEntries(main)).toBe(2);
+    });
+
+    it("leaves the feed's self link on the address without it", async () => {
+      const { app, services } = createFeedTestApp();
+      await createNotes(services, 1);
+
+      const xml = await (await app.request("/latest/feed?limit=10")).text();
+
+      expect(xml).toContain(
+        `<link href="http://localhost:${DEFAULT_APP_PORT}/latest/feed" rel="self"/>`,
+      );
+    });
+
+    it("renders past a hundred entries within D1's bound-parameter limit", async () => {
+      const { app, services, sqlite } = createFeedTestApp();
+      await createNotes(services, 120, { featured: true });
+      enforceD1BoundParameterLimit(sqlite);
+
+      for (const path of ["/latest/feed", "/featured/feed"]) {
+        const res = await app.request(`${path}?limit=120`);
+        expect(res.status).toBe(200);
+        expect(countEntries(await res.text())).toBe(120);
+      }
+    });
+  });
+
   describe("RSS_PUBLISH_DELAY_SECONDS env var", () => {
     it("includes the exact 300-second boundary and excludes newer Posts", async () => {
       const currentTime = 2_000_000;
@@ -702,6 +834,37 @@ describe("Atom Feed Routes", () => {
       expect(xml).toContain("<hr/>");
     });
 
+    it("names a reply by its alias, the way the site does", async () => {
+      const { app, services } = createFeedTestApp();
+
+      const root = await services.posts.create({
+        format: "note",
+        title: "Aliased Thread Root",
+        bodyMarkdown: "Root content",
+        status: "published",
+        featured: true,
+      });
+      const reply = await services.posts.create({
+        format: "note",
+        bodyMarkdown: "Reply content",
+        status: "published",
+        replyToId: root.id,
+      });
+      await services.paths.create({
+        path: "/notes/the-reply",
+        kind: "alias",
+        postId: reply.id,
+      });
+
+      for (const path of ["/latest/feed", "/featured/feed"]) {
+        const xml = await (await app.request(path)).text();
+        // The row, the fold's `latest`, and the inline reply link all name
+        // the reply by the address the site uses, not by its slug.
+        expect(xml).toContain('href="http://localhost:3000/notes/the-reply"');
+        expect(xml).not.toContain(`/${reply.slug}"`);
+      }
+    });
+
     it("delays new replies inside an already eligible Thread", async () => {
       const currentTime = 2_000_000;
       const dateNow = vi.spyOn(Date, "now").mockReturnValue(currentTime * 1000);

package/src/routes/feed/__tests__/sitemap.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
 import type { Bindings } from "../../../types.js";
 import type { AppVariables } from "../../../types/app-context.js";
@@ -154,6 +154,73 @@ describe("Sitemap Routes", () => {
       expect(indices).toEqual([...indices].sort((a, b) => a - b));
     });
 
+    // A Thread root's page renders its replies, so anything that changes a
+    // reply changes the page. Unlike ordering, edits count for <lastmod> —
+    // the page really did change.
+    it("moves <lastmod> when a reply is added", async () => {
+      const { app, services } = createSitemapTestApp();
+      const readLastmod = async () => {
+        const xml = await (await app.request("/sitemap-posts-1.xml")).text();
+        return /<lastmod>([^<]+)<\/lastmod>/.exec(xml)?.[1];
+      };
+
+      vi.useFakeTimers();
+      try {
+        // lastmod is a date, so the two writes need to land on different days.
+        vi.setSystemTime(new Date("2026-03-01T00:00:00Z"));
+        const root = await services.posts.create({
+          format: "note",
+          bodyMarkdown: "root",
+          title: "Threaded",
+          status: "published",
+        });
+        expect(await readLastmod()).toBe("2026-03-01");
+
+        vi.setSystemTime(new Date("2026-03-05T00:00:00Z"));
+        await services.posts.create({
+          format: "note",
+          bodyMarkdown: "reply",
+          replyToId: root.id,
+          status: "published",
+        });
+        expect(await readLastmod()).toBe("2026-03-05");
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("ignores a draft reply in <lastmod>", async () => {
+      const { app, services } = createSitemapTestApp();
+      const readLastmod = async () => {
+        const xml = await (await app.request("/sitemap-posts-1.xml")).text();
+        return /<lastmod>([^<]+)<\/lastmod>/.exec(xml)?.[1];
+      };
+
+      vi.useFakeTimers();
+      try {
+        vi.setSystemTime(new Date("2026-03-01T00:00:00Z"));
+        const root = await services.posts.create({
+          format: "note",
+          bodyMarkdown: "root",
+          title: "Threaded",
+          status: "published",
+        });
+
+        vi.setSystemTime(new Date("2026-03-05T00:00:00Z"));
+        await services.posts.create({
+          format: "note",
+          bodyMarkdown: "unpublished reply",
+          replyToId: root.id,
+          status: "draft",
+        });
+
+        // Not on the page, so it must not claim the page changed.
+        expect(await readLastmod()).toBe("2026-03-01");
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
     it("excludes private posts, replies, and drafts", async () => {
       const { app, services } = createSitemapTestApp();
       const root = await services.posts.create({

package/src/routes/feed/feed.ts

@@ -28,9 +28,13 @@ import type {
 import type { AppVariables } from "../../types/app-context.js";
 import { defaultFeedRenderer } from "../../lib/feed.js";
 import {
+  buildFeedDiscoveryFields,
+  featuredFeedSelection,
   getFeedEntryUpdatedAt,
+  getFeedLimit,
   getRssPublishedBefore,
-  RSS_FEED_CACHE_CONTROL,
+  latestFeedSelection,
+  renderFeed,
 } from "../../lib/feed-policy.js";
 import { buildMediaMap } from "../../lib/media-helpers.js";
 import { getI18n } from "../../i18n/index.js";
@@ -38,6 +42,7 @@ import { FORMATS } from "../../types/constants.js";
 
 import { createMediaContext, toPostViews } from "../../lib/view.js";
 import { toAbsoluteSiteUrl, toPublicPath } from "../../lib/url.js";
+import { getViewLang, viewBasePath } from "../../lib/view-language.js";
 import { toPlainText } from "../../lib/markdown.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
@@ -82,12 +87,18 @@ async function loadMediaMap(
 
 /**
  * Build thread replies as PostView[] for a given root post from a thread map.
+ *
+ * Replies take the alias map too. A reply's permalink is what `<jant:post>`
+ * rows, the fold's `gap` and `latest`, and every `media:content` name it by,
+ * and a consumer keys on that address — so it has to be the address the site
+ * itself uses, which is the reply's first alias when it has one.
  */
 function buildThreadReplies(
   rootId: string,
   threadMap: Map<string, Post[]>,
   mediaMap: ReturnType<typeof buildMediaMap>,
   mediaCtx: ReturnType<typeof createMediaContext>,
+  aliasMap: Map<string, string>,
 ) {
   const thread = threadMap.get(rootId);
   if (!thread || thread.length <= 1) return undefined;
@@ -100,9 +111,20 @@ function buildThreadReplies(
         mediaAttachments: mediaMap.get(r.id) ?? [],
       })),
     mediaCtx,
+    undefined,
+    aliasMap,
   );
 }
 
+/** The first alias of each post that has one: the address the site uses. */
+function toAliasMap(aliasesMap: Map<string, string[]>): Map<string, string> {
+  const aliasMap = new Map<string, string>();
+  for (const [id, aliases] of aliasesMap) {
+    if (aliases[0]) aliasMap.set(id, aliases[0]);
+  }
+  return aliasMap;
+}
+
 /**
  * Collect all reply IDs from a thread map (excluding root posts).
  */
@@ -126,13 +148,12 @@ async function buildLatestFeedData(
   format?: Format,
 ): Promise<{ posts: Post[]; postViews: FeedPostView[] }> {
   const posts = await c.var.services.posts.list({
-    status: "published",
-    excludeReplies: true,
-    excludeLatestHidden: true,
-    excludePrivate: true,
+    ...latestFeedSelection({
+      lang: getViewLang(c) ?? undefined,
+      publishedBefore,
+    }),
     format,
     ignorePinnedSort: true,
-    publishedBefore,
     limit: feedLimit,
   });
 
@@ -146,17 +167,19 @@ async function buildLatestFeedData(
     c.var.services.paths.getPostAliases(postIds),
   ]);
 
-  // Load media for replies
+  // Replies are only known once the threads are, so their media and aliases
+  // come in a second round.
   const replyIds = collectReplyIds(threadMap);
-  const replyMediaMap =
-    replyIds.length > 0 ? await loadMediaMap(c, replyIds, mediaCtx) : mediaMap;
+  const [replyMediaMap, replyAliasesMap] =
+    replyIds.length > 0
+      ? await Promise.all([
+          loadMediaMap(c, replyIds, mediaCtx),
+          c.var.services.paths.getPostAliases(replyIds),
+        ])
+      : [mediaMap, new Map<string, string[]>()];
   // Merge reply media into main map
   const mergedMediaMap = new Map([...mediaMap, ...replyMediaMap]);
-
-  const aliasMap = new Map<string, string>();
-  for (const [id, aliases] of aliasesMap) {
-    if (aliases[0]) aliasMap.set(id, aliases[0]);
-  }
+  const aliasMap = toAliasMap(new Map([...aliasesMap, ...replyAliasesMap]));
 
   const postViews = toPostViews(
     posts.map((p) => ({
@@ -177,6 +200,7 @@ async function buildLatestFeedData(
         threadMap,
         mergedMediaMap,
         mediaCtx,
+        aliasMap,
       ),
     };
   });
@@ -197,9 +221,10 @@ async function buildFeaturedFeedData(
   publishedBefore: number,
 ): Promise<{ posts: Post[]; postViews: FeedPostView[] }> {
   const rootIds = await c.var.services.posts.listFeaturedThreadRootIds({
-    status: "published",
-    excludePrivate: true,
-    publishedBefore,
+    ...featuredFeedSelection({
+      lang: getViewLang(c) ?? undefined,
+      publishedBefore,
+    }),
     limit: feedLimit,
   });
 
@@ -224,7 +249,7 @@ async function buildFeaturedFeedData(
   const postIds = posts.map((p) => p.id);
   const mediaCtx = createMediaContext(c.var.appConfig);
 
-  // Collect all post IDs (roots + replies) for media loading
+  // Collect all post IDs (roots + replies) for media and alias loading
   const allPostIds = new Set(postIds);
   for (const thread of threadMap.values()) {
     for (const post of thread) {
@@ -234,13 +259,9 @@ async function buildFeaturedFeedData(
 
   const [mediaMap, aliasesMap] = await Promise.all([
     loadMediaMap(c, [...allPostIds], mediaCtx),
-    c.var.services.paths.getPostAliases(postIds),
+    c.var.services.paths.getPostAliases([...allPostIds]),
   ]);
-
-  const aliasMap = new Map<string, string>();
-  for (const [id, aliases] of aliasesMap) {
-    if (aliases[0]) aliasMap.set(id, aliases[0]);
-  }
+  const aliasMap = toAliasMap(aliasesMap);
 
   const postViews = toPostViews(
     posts.map((p) => ({
@@ -257,7 +278,13 @@ async function buildFeaturedFeedData(
     return {
       ...postView,
       feedUpdatedAt: getFeedEntryUpdatedAt(post, thread),
-      threadReplies: buildThreadReplies(post.id, threadMap, mediaMap, mediaCtx),
+      threadReplies: buildThreadReplies(
+        post.id,
+        threadMap,
+        mediaMap,
+        mediaCtx,
+        aliasMap,
+      ),
     };
   });
 
@@ -284,8 +311,9 @@ export async function buildFeedData(
   const siteName = appConfig.siteName;
   const siteDescription = toPlainText(appConfig.siteDescription);
   const siteUrl = appConfig.siteUrl;
-  const siteLanguage = appConfig.siteLanguage;
-  const feedLimit = appConfig.rssFeedLimit;
+  // A language view's feed is that language's feed, so it declares it.
+  const siteLanguage = getViewLang(c) ?? appConfig.siteLanguage;
+  const feedLimit = getFeedLimit(c);
   const publishedBefore = getRssPublishedBefore(
     appConfig.rssPublishDelaySeconds,
   );
@@ -297,6 +325,7 @@ export async function buildFeedData(
       : await buildLatestFeedData(c, feedLimit, publishedBefore, opts.format);
 
   return {
+    ...buildFeedDiscoveryFields(c),
     siteName,
     siteDescription,
     siteUrl,
@@ -318,10 +347,11 @@ export async function buildFeedData(
             }),
           )}`,
     selfUrl: toAbsoluteSiteUrl(
-      opts.selfPath,
+      `${viewBasePath(c)}${opts.selfPath}`,
       siteUrl,
       appConfig.sitePathPrefix,
     ),
+    siteIconUrl: appConfig.siteAvatarUrl || undefined,
     posts: postViews,
   };
 }
@@ -338,21 +368,20 @@ export function parseFormatQuery(c: Context<Env>): Format | undefined {
   return undefined;
 }
 
-export function renderFeed(xml: string) {
-  return new Response(xml, {
-    headers: {
-      "Content-Type": "application/atom+xml; charset=utf-8",
-      "Cache-Control": RSS_FEED_CACHE_CONTROL,
-    },
-  });
-}
-
-// Atom — /feed
-feedRoutes.get("/", async (c) => {
+/**
+ * Render the site's main Atom feed for the current view language.
+ *
+ * @param c - Hono context
+ * @returns Atom feed response
+ */
+export async function renderMainFeed(c: Context<Env>): Promise<Response> {
   const kind = c.var.appConfig.mainRssFeed === "latest" ? "latest" : "featured";
   const feedData = await buildFeedData(c, { kind, selfPath: "/feed" });
   return renderFeed(defaultFeedRenderer(feedData));
-});
+}
+
+// Atom — /feed
+feedRoutes.get("/", renderMainFeed);
 
 // Legacy — /feed/latest moved to the canonical /latest/feed. Kept
 // indefinitely as a 308 so old subscribers don't break; preserves the