Додати живе коментування до додатків Val Town

Val Town працює з TypeScript на Deno, тому val — це справжній сервер. Це робить його хорошим варіантом для FastComments: віджет — це тег script на сторінці, і все, що потребує секрету, наприклад Secure SSO або перевірка вебхука, може виконуватись на сервері в тому ж val.

У цьому посібнику розглядається додавання віджета коментарів до HTTP val, відображення кількості коментарів на головній сторінці, входження користувачів за допомогою облікового запису Val Town, який у них вже є, та отримання вебхуків коментарів.

Для спроби обліковий запис не потрібен. У прикладах використовується tenantId: "demo", спільна пісочниця, а крок 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 val

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 secret.

Tenant ID є публічним і належить до коду браузера. API secret – ні, і нічого на цій сторінці не потребує його.

Прочитати його з змінної середовища

Val Town vals є публічними у безкоштовному тарифі, тому їх джерело доступне всім. Тримайте будь‑яку конфіденційну інформацію у змінних середовища, читаючи їх за допомогою Deno.env.get:

config.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 з другої причини: перемішування val копіює ключі змінних середовища, але не їхні значення. Секрет, збережений у змінній середовища, не переходить разом з вашим val у обліковий запис іншої людини. Секрет, записаний у файл, переходить.

Повернення до "demo" дозволяє val працювати для будь‑кого, хто перемішує його перед встановленням власного tenant.

EU облікові записи

Обліковий запис, його дані та ключі розташовані в одному регіоні. Якщо ваш був створений на eu.fastcomments.com, кожна конфігурація віджету також потребує region: "eu", і скрипти завантажуються з cdn-eu.fastcomments.com. Інакше залиште обидва без змін.

Кількість коментарів на індексній сторінці

На індексній сторінці не рендерьте один віджет підрахунку коментарів на рядок. Це означає один запит на пост. Використовуйте масовий підрахунок, який робить один запит для всієї сторінки.

Позначте кожен рядок urlId, який використовує його тема, потім завантажте масовий віджет один раз:

Масові підрахунки коментарів на індексній сторінці

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, який використовує віджет коментарів поста. Якщо віджет використовує slug, маркер використовує slug. Невідповідність показує нуль у темі, яка має коментарі.

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

Захищений SSO за допомогою std/oauth

Якщо ваш val вже знає, хто є відвідувачем, Secure SSO передає цю ідентичність віджету, тому користувач ніколи не бачить другий вхід. Не потрібно створювати кінцеві точки і нічого викликати під час виконання: ви обчислюєте три значення на сервері та передаєте їх у конфігурацію віджета.

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

Build the payload on the server

Секрет 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 для вас. Зауважте, що вихід (logout) — це POST, тоді як віджет переходить за logoutURL за допомогою GET, тому вкажіть logoutURL на невеликий маршрут вашого додатку, який виконує POST.

Коли відвідувач виходить з системи, передайте sso лише з loginURL. Тоді віджет покаже запит на вхід замість анонімного поля коментаря.

Things that go wrong

timestamp — це мілісекунди епохи, не повинен бути в майбутньому і не повинен бути старшим за два дні. Генеруйте його на сервері в тому ж запиті, де обчислюється хеш. Генерація в браузері — це класична помилка: значення відрізняється від того, що було захешовано, і кожен коментар відхиляється.

Ніколи не встановлюйте isAdmin або isModerator з провайдера ідентифікації. Вхід за допомогою облікового запису Val Town нічого не говорить про те, хто повинен модерувати ваш сайт.

Перегляньте посібник SSO для повного списку полів, потоків з груповим доступом та значків.

Отримання вебхукiв

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) {
  // The exact bytes that arrived. Do NOT use c.req.json() and re-serialize.
  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 });
  // Reject stale deliveries so a captured request cannot be replayed later.
  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 });
  }
  // ...handle JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Дві речі, які можуть зіпсувати

Перевірте сирі байти. Парсинг JSON та його повторна серіалізація змінює порядок ключів і пробіли, тому хеш відрізняється і кожна доставка провалюється без очевидної причини. Це звичайна причина, чому отримувач вебхука «просто не працює».

Порівнюйте за постійний час. Проста операція === над підписом розкриває, скільки байтів збіглося, чого достатньо, щоб підробити один байт за раз.

Обробка подій

Відповідайте швидко. FastComments повторює запит у випадку відповіді, відмінної від 2xx, і кінцева точка, яка постійно помиляється, зрештою автоматично вимикається, тому реальну роботу виконуйте після відповіді, а не вбудовано.

Зробіть цю роботу ідемпотентною за ідентифікатором коментаря. Повторна спроба підписується новим часовим міткою, і той самий ідентифікатор коментаря надходить знову при редагуванні та видаленні, тому немає стабільного критерію для дедуплікації.

Приклад Vals

Чотири публічних валів, які ви можете реміксити, кожен охоплює одну частину цього посібника.

Blog with comments (live) — це Markdown‑блог з гілкою під кожним постом і підрахунком коментарів у масиві на індексі. Він працює відразу після реміксу, і одна змінна середовища вказує його на ваш власний обліковий запис.

SSO demo (live) входить відвідувача за допомогою їхнього облікового запису Val Town і передає цю ідентичність віджету, тому другий вхід не потрібен.

Webhook receiver (live) перевіряє HMAC‑підпис кожної доставки і зберігає події в SQLite. Має кнопку, яка підписує тестове навантаження і надсилає його самому собі, тож ви можете спостерігати успішну верифікацію перед налаштуванням реального вебхука.

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

Ті ж навички можна встановити будь-де за допомогою npx skills add fastcomments/skills.

Помилки домену

Як тільки ви вимкнете орендаря demo, віджет може відмовитися завантажуватись з помилкою авторизації. Це відбувається тому, що FastComments не знає, що йому слід дозволити використання вашого облікового запису на цьому домені.

Перейдіть сюди, щоб додати ваш сайт до вашого облікового запису.

Val Town варто розглянути ще раз, оскільки val може бути доступним за більш ніж одним ім'ям хоста:

Кожен HTTP val має довгий стандартний кінцевий пункт, <org>--<id>.web.val.run.
Присвоєння власного піддомена додає <name>.val.run.
Користувацький домен додає третій.
Гілки отримують власні URL-адреси.

Додайте ті імена хостів, з яких ви фактично обслуговуєте віджет. Якщо ви присвоїте піддомен після налаштування, додайте його також, інакше віджет працюватиме за старим URL і не працюватиме за новим.

Встановлення Val Town

Додати живе коментування до додатків Val Town

Крок 1: Додати віджет

Виберіть urlId перед випуском

Збереження коментарів без JavaScript

Крок 2: Використовувати свій власний обліковий запис

Прочитати його з змінної середовища

EU облікові записи

Кількість коментарів на індексній сторінці

Захищений SSO за допомогою std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Отримання вебхукiв

Дві речі, які можуть зіпсувати

Обробка подій

Приклад Vals

Помилки домену

Мова 🇺🇦 Українська

Встановлення Val Town

Додати живе коментування до додатків Val Town

Крок 1: Додати віджет

Виберіть urlId перед випуском

Збереження коментарів без JavaScript

Крок 2: Використовувати свій власний обліковий запис

Прочитати його з змінної середовища

EU облікові записи

Кількість коментарів на індексній сторінці

Захищений SSO за допомогою std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Отримання вебхукiв

Дві речі, які можуть зіпсувати

Обробка подій

Приклад Vals

Помилки домену