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

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

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

Для спроби обліковий запис не потрібен. У прикладах використовується tenantId: "demo", спільна пісочниця, а крок 2 охоплює перехід на ваш власний.

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

Віджет — це тег script та елемент-контейнер, тому він вписується в те, що ваш val вже рендерить. Цей приклад використовує Hono JSX, який використовується в HTTP-шаблонах Val Town.

Віджет коментарів у 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 визначає, у яку гілку потрапить коментар. Якщо його не встановити, за замовчуванням використовується очищена версія URL поточної сторінки, а саме це змінюється на Val Town: val має довгий ім'я хоста *.web.val.run, доки ви не прив'яжете субдомен, гілки отримують власні URL, а перейменування сторінки змінює шлях. Кожна варіація мовчки стає окремою порожньою гілкою, і симптом виглядає як «мої коментарі зникли».

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

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

FastComments рендерить повну гілку на сервері, і val може вставити її в блок <noscript>:

Резервний варіант без 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. Серверна версія підтримує анонімні та авторизовані коментарі, SSO та вкладені відповіді.

Крок 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 не змінюється.

Формування payload на сервері

API secret підписує payload і ніколи не повинен потрапляти в код браузера. Встановіть 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 }. Саме ці три значення потрапляють у браузер. Секрет підписує їх, а потім відкидається, тож нічого на сторінці не дозволить зловмиснику підробити іншого користувача.

Передача у віджет

Widget config with 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. Тоді віджет покаже запрошення до входу замість анонімного поля коментарів.

Типові проблеми

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

Ніколи не встановлюйте 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) {
  // 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

Як тільки FastComments буде встановлено у вашому додатку Val Town, ви також зможете проводити живі опитування безпосередньо в коментарях. Увімкніть Enable Polls у налаштуваннях налаштування віджету, і кнопка опитування з'явиться на панелі інструментів коментаря. Опитування можуть мати від 2 до 10 варіантів, результати оновлюються в режимі реального часу для всіх на сторінці, і ви обираєте, хто може створювати опитування та чи вимагає голосування входу в систему. Більше нічого встановлювати на Val Town не потрібно.

Try the Live Polls demo або прочитайте Polls documentation, щоб налаштувати їх.

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

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

Опитування

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

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

Виберіть urlId перед публікацією

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

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

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

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

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

Захищений SSO з std/oauth

Формування payload на сервері

Передача у віджет

Типові проблеми

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

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

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

Приклад Vals

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

Додати опитування до вашого додатку Val Town