Добавете живо коментиране към приложенията на Val Town

Val Town изпълнява TypeScript върху Deno, така че val е истински сървър. Това го прави подходящ за FastComments: уиджетът е script таг в страницата и всичко, което изисква тайна, като Secure SSO или проверка на webhook, може да се изпълни от сървърната страна в същия val.

Този наръчник обхваща добавянето на уиджета за коментари към HTTP val, показването на броя коментари на индексната страница, влизането на потребителите с акаунта им във Val Town, който вече имат, и получаването на webhook‑и за коментари.

Не ви е необходим акаунт, за да го изпробвате. Примерите използват tenantId: "demo", споделен sandbox, а Стъпка 2 обяснява как да преминете към ваш собствен.

Стъпка 1: Добавете уиджета

The widget is a script tag and a container element, so it drops into whatever your val already renders. This example uses Hono JSX, which is what Val Town's HTTP templates use.

Уиджет за коментари в HTTP вал

Copy

Run

/** @jsxImportSource npm:hono@4/jsx */
import { Hono } from "npm:hono@4";
const app = new Hono();
app.get("/:slug", (c) => {
  const slug = c.req.param("slug");
  const url = new URL(c.req.path, c.req.url).toString();
  const config = JSON.stringify({
    tenantId: "demo",
    urlId: slug,
    url,
  });
  return c.html(
    <html>
      <body>
        <h1>{slug}</h1>
        <div id="fastcomments-widget"></div>
        <script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
        <script
          dangerouslySetInnerHTML={{
            __html:
              `window.FastCommentsUI(document.getElementById("fastcomments-widget"), ${config});`,
          }}
        />
      </body>
    </html>,
  );
});
export default app.fetch;

Изберете urlId преди да пуснете

urlId decides which thread a comment lands in. Leave it unset and it defaults to a cleaned version of the current page URL, which is exactly the thing that changes on Val Town: a val has a long *.web.val.run hostname until you claim a subdomain, branches get their own URLs, and renaming a page changes the path. Each variation silently becomes a separate, empty thread, and the symptom reads as "my comments disappeared".

Set it to something stable that you control, like the post slug or a database id, as above. Pass url too, so notification emails and the moderation tools can link back to the real page.

Запазване на коментари без JavaScript

FastComments renders a full thread server-side, which a val can drop into a <noscript> block:

Резервен вариант без JavaScript

Copy

Run

<noscript>
  <iframe src="https://fastcomments.com/ssr/comments?tenantId=demo&urlId=POST_SLUG&url=PAGE_URL"
          title="FastComments" width="100%" height="1500px" frameborder="0"
          style="width: 1px !important; min-width: 100% !important; border: none !important;"></iframe>
</noscript>

URL-encode the parameters. The server-side version supports anonymous and logged-in commenting, SSO, and nested replies.

Стъпка 2: Използвайте вашия собствен акаунт

tenantId: "demo" е споделен публичен пясъчник. Работи без регистрация, затова примерите го използват, но всички останали, които използват FastComments, пишат в същите теми и всеки може да ги модерира. Превключете преди да публикувате каквото и да е, което ви е важно.

Вашият tenant ID е на страница за API тайни.

Tenant ID е публичен и принадлежи в кода на браузъра. API тайна не е, и нищо на тази страница не се нуждае от такава.

Прочетете го от променлива на околната среда

Val Town валовете са публични в безплатния слой, затова техният източник е достъпен за всички. Пазете всичко чувствително в променливи на околната среда, прочетете с Deno.env.get:

конфиг.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Само акаунти, създадени на eu.fastcomments.com задават това, на "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Това е по-важно от обикновено в Val Town поради втора причина: ремиксирането на вал копира ключовете на променливите на околната среда, но не техните стойности. Тайна, съхранена в променлива на околната среда, не следва вашия вал в акаунта на друг човек. Тайна, записана във файл, го прави.

Връщането към "demo" запазва валът работещ за всеки, който го ремиксира, преди да зададе свой собствен tenant.

EU акаунти

Акаунт, неговите данни и ключове живеят в един регион. Ако вашият е създаден на eu.fastcomments.com, всяка конфигурация на уиджет също се нуждае от region: "eu", а скриптовете се зареждат от cdn-eu.fastcomments.com. В противен случай оставете и двете както са.

Брой коментари на индексната страница

На индексна страница не рендерирайте по един widget за брой коментари на ред. Това е една заявка за всяка публикация. Използвайте груповия брой, който изпраща една единствена заявка за цялата страница.

Маркирайте всеки ред с urlId, който използва нишката му, след което заредете груповия widget еднократно:

Групови броячи на коментари в индекс

Copy

Run

<ul>
  {posts.map((post) => (
    <li>
      <a href={post.slug}>{post.title}</a>{" "}
      <span class="fast-comments-count" data-fast-comments-url-id={post.slug}></span>
    </li>
  ))}
</ul>
<script
  dangerouslySetInnerHTML={{
    __html: `window.FastCommentsBulkCountConfig = ${
      JSON.stringify({ tenantId: TENANT_ID })
    };`,
  }}
/>
<script src="https://cdn.fastcomments.com/js/embed-widget-comment-count-bulk.min.js"></script>

Скриптът намира всеки елемент .fast-comments-count на страницата и попълва неговия брой.

data-fast-comments-url-id трябва да съвпада с urlId, който използва widget‑ът за коментари на публикацията. Ако widget‑ът използва slug, маркерът използва slug. При несъответствие се показва нула за нишка, която има коментари.

Скриптът проверява наличието на window.FastCommentsBulkCountConfig, затова няма значение дали конфигурацията е зададена преди или след етикета на скрипта.

Сигурен SSO с std/oauth

Ако вашият val вече знае кой е посетителят, Secure SSO предава тази идентичност на уиджета, така че той никога да не вижда второ влизане. Няма нужда от създаване на крайни точки и нищо не се извиква по време на изпълнение: изчислявате три стойности на сървъра и ги предавате в конфигурацията на уиджета.

Val Town предоставя вход без конфигурация с std/oauth, така че посетителят може да влезе с Val Town акаунта, който вече притежава. Заменете това с каквото вашето приложение използва; частта на FastComments остава непроменена.

Създаване на полезния товар на сървъра

Тайната на API подписва полезния товар и никога не трябва да достигне до кода в браузъра. Инсталирайте SDK от npm, което работи директно в Deno средата на Val Town:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // id must be stable for the same person, or they get a new comment identity on every login.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // email is required and must be unique.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // username is required and cannot be an email.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() връща { userDataJSONBase64, verificationHash, timestamp }. Тези три стойности са всичко, което достига до браузъра. Тайната ги подписва и след това се изхвърля, така че нищо в страницата не позволява на читателя да подправи различен потребител.

Предайте го на уиджета

Конфигурация на уиджет с SSO

Copy

Run

import { getOAuthUserData, oauthMiddleware } from "https://esm.town/v/std/oauth/middleware.ts";
app.get("/", async (c) => {
  const session = await getOAuthUserData(c.req.raw);
  const user = session?.user;
  const config = {
    tenantId: TENANT_ID,
    urlId: "my-thread",
    ...(user
      ? { sso: { ...buildSSOPayload(user), logoutURL: "/logout" } }
      : { sso: { loginURL: "/auth/login" } }),
  };
  // ...render the widget with this config
});
export default oauthMiddleware(app.fetch);

oauthMiddleware добавя GET /auth/login, GET /auth/callback и POST /auth/logout за вас. Обърнете внимание, че изходът е POST, докато уиджетът навигира към logoutURL с GET, затова насочете logoutURL към малка ваша рута, която изпраща POST заявка.

Когато посетителят е излязъл, предайте sso само с loginURL. Уиджетът тогава показва прозорец за вход вместо анонимен кутия за коментари.

Неочаквани проблеми

timestamp е епоха в милисекунди, не трябва да бъде в бъдещето и не трябва да е по-стар от два дни. Генерирайте го на сървъра в същата заявка, която изчислява хеша. Генерирането му в браузъра е класическа грешка: стойността се различава от тази, която е била хеширана, и всеки коментар се отхвърля.

Никога не задавайте isAdmin или isModerator от доставчика на идентичност. Влизането с Val Town акаунт не казва нищо за това кой трябва да модерира вашия сайт.

Вижте ръководството за SSO за пълен списък на полетата, нишки с групово ограничение и значки.

Получаване на уебкуки

A val е естествен получател на уебхук: има стабилен URL, може да проверява подпис и има вградено SQLite и съхранение на блобове.

FastComments подписва ${timestamp}.${body} с API тайната на вашия акаунт и изпраща две заглавки:

Заглавки на уебхук

Copy

Run

X-FastComments-Timestamp: 1789004710        unix seconds, not milliseconds
X-FastComments-Signature: sha256=<hex>

Методът носи събитието: PUT за създаден или актуализиран коментар, DELETE за изтрит.

Проверка на доставката

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Точните байтове, които пристигнаха. НЕ използвайте c.req.json() и повторно сериализиране.
  const rawBody = await c.req.raw.text();
  const timestamp = c.req.raw.headers.get("X-FastComments-Timestamp");
  const signature = c.req.raw.headers.get("X-FastComments-Signature");
  if (!timestamp || !signature) return new Response("Missing headers", { status: 400 });
  // Отхвърляне на остарели доставки, за да не може прихванатата заявка да бъде повторно изпълнена по-късно.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) {
    return new Response("Timestamp outside window", { status: 400 });
  }
  const expected = "sha256=" + createHmac("sha256", Deno.env.get("FASTCOMMENTS_API_SECRET"))
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = new TextEncoder().encode(signature);
  const b = new TextEncoder().encode(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return new Response("Signature mismatch", { status: 401 });
  }
  // ...обработете JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Две неща, които късат

Проверете суровите байтове. Парсирането на JSON и повторното му сериализиране променя реда на ключовете и whitespace, така че хешът се различава и всяка доставка се проваля без очевидна причина. Това е обичайната причина уебхук получателят „просто не работи“.

Сравнявайте в константно време. Обикновен === върху подписа разкрива колко байта съвпадат, което е достатъчно за фалшифициране по един байт наведнъж.

Обработка на събития

Отговаряйте бързо. FastComments прави повторни опити при не‑2xx отговор, а крайна точка, която продължава да се проваля, в крайна сметка се изключва автоматично, затова извършвайте реалната работа след отговора, а не вмъкната.

Направете тази работа идемпотентна спрямо ID‑то на коментара. При повторен опит подписът се генерира отново с нов timestamp, а същото ID на коментара се получава отново при редактиране и изтриване, така че няма стабилна стойност за дедупликация.

Примерни стойности

Четири публични vals, които можете да ремиксирате, всяка от тях обхваща една част от това ръководство.

Blog with comments (live) е Markdown блог с нишка под всяка публикация и общи броячи на коментари в индекса. Работи веднага след като го ремиксирате, а една променлива на средата го насочва към вашия собствен акаунт.

SSO demo (live) вписва посетителя с техния Val Town акаунт и предава тази идентичност на уиджета, така че няма второ влизане.

Webhook receiver (live) проверява HMAC подписа при всяка доставка и съхранява събития в SQLite. Има бутон, който подписва тестово натоварване и го изпраща към себе си, така че можете да видите проверката да успее преди да конфигурирате истински webhook.

Agent skills (live) е библиотека от FastComments агентски умения, обхващащи уиджета, SSO, REST API, модериране и миграция от Disqus. Ремиксирайте я и агентът на Val Town, Townie, автоматично взема уменията от skills/, така че вашият агент знае как да настрои коментарите без да копирате документацията в чата.

Същите умения се инсталират навсякъде другаде с npx skills add fastcomments/skills.

Грешки в домейна

Once you switch off the demo tenant, the widget may refuse to load with an authorization error. This is because FastComments doesn't know it's supposed to allow your account to be used on that domain.

Отидете тук, за да добавите вашия сайт към вашия акаунт.

Val Town is worth a second look here, because a val can be reachable at more than one hostname:

Every HTTP val has a long default endpoint, <org>--<id>.web.val.run.
Claiming a custom subdomain adds <name>.val.run.
A персонализиран домейн adds a third.
Branches get their own URLs.

Add whichever hostnames you actually serve the widget from. If you claim a subdomain after setting things up, add that too, or the widget works on the old URL and fails on the new one.

Език 🇧🇬 Български

Инсталиране на Val Town

Добавете живо коментиране към приложенията на Val Town

Стъпка 1: Добавете уиджета

Изберете urlId преди да пуснете

Запазване на коментари без JavaScript

Стъпка 2: Използвайте вашия собствен акаунт

Прочетете го от променлива на околната среда

EU акаунти

Брой коментари на индексната страница

Сигурен SSO с std/oauth

Създаване на полезния товар на сървъра

Предайте го на уиджета

Неочаквани проблеми

Получаване на уебкуки

Две неща, които късат

Обработка на събития

Примерни стойности

Грешки в домейна