Добавьте живой комментарий в приложения 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‑секрета.

Tenant ID является публичным и должен находиться в коде браузера. API‑секрет — нет, и ничего на этой странице не требует его.

Считать из переменной окружения

Val Town vals публичны в бесплатном тарифе, поэтому их исходный код доступен всем. Храните любые конфиденциальные данные в переменных окружения, считывайте их с помощью Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Only accounts created on eu.fastcomments.com set this, to "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`, поэтому не имеет значения, задаёте вы конфигурацию до или после тега script.

Защищенный 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 за вас. Обратите внимание, что выход (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 });
  }
  // ...handle JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Два момента, которые могут вызвать проблемы

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

Сравнивайте за постоянное время. Обычное === по подписи раскрывает, сколько байтов совпало, чего достаточно, чтобы подделать один байт за раз.

Обработка событий

Отвечайте быстро. FastComments повторяет запрос при ответе, не являющемся 2xx, и конечная точка, постоянно вызывающая ошибки, в конце концов автоматически отключается, поэтому выполняйте реальную работу после отправки ответа, а не внутри него.

Сделайте работу идемпотентной по ID комментария. При повторе запрос подписывается заново с новым timestamp, и тот же ID комментария приходит снова при редактировании и удалении, поэтому нет стабильного признака для дедупликации.

Примеры Vals

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

Блог с комментариями (вживую) — это Markdown‑блог с веткой комментариев под каждой записью и массовыми подсчётами комментариев в индексе. Он работает сразу после ремикса, и одна переменная окружения указывает его на ваш собственный аккаунт.

Демонстрация SSO (вживую) регистрирует посетителя с помощью их аккаунта Val Town и передаёт эту идентичность виджету, так что вторичный вход не требуется.

Получатель вебхуков (вживую) проверяет HMAC‑подпись каждой доставки и сохраняет события в SQLite. Он имеет кнопку, которая подписывает тестовый payload и отправляет его себе, так что вы можете увидеть успешную проверку перед настройкой реального вебхука.

Навыки агента (вживую) — это библиотека навыков агента 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.
Пользовательский домен (custom domain) добавляет третий.
Ветки получают свои собственные URL-адреса.

Добавьте любые имена хостов, с которых вы действительно обслуживаете виджет. Если вы заявите поддомен после настройки, добавьте его тоже, иначе виджет будет работать по старому URL и не будет работать по новому.

Язык 🇷🇺 Русский

Установка Val Town

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

Шаг 1: Добавить виджет

Выберите urlId перед публикацией

Сохранение комментариев без JavaScript

Шаг 2: Использовать свой аккаунт

Считать из переменной окружения

EU‑аккаунты

Количество комментариев на странице индекса

Скрипт опрашивает window.FastCommentsBulkCountConfig, поэтому не имеет значения, задаёте вы конфигурацию до или после тега script.

Защищенный SSO с std/oauth

Создание полезной нагрузки на сервере

Передача в виджет

Возможные проблемы

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

Два момента, которые могут вызвать проблемы

Обработка событий

Примеры Vals

Ошибки домена

Скрипт опрашивает `window.FastCommentsBulkCountConfig`, поэтому не имеет значения, задаёте вы конфигурацию до или после тега script.