Перед запуском
- Node.js 22.13+ в ветке 22 или Node.js 24 и поддерживаемая swm-uws платформа: macOS arm64/x64, Windows x64, Linux x64 glibc.
- Во всех примерах используется loopback и порт 3000. Останавливайте текущий процесс через Ctrl+C перед следующим рецептом.
- Команды проверки рассчитаны на Bash и curl. Для SIGINT/SIGTERM и закрытия логгера перенесите рецепт в ExampleService из быстрого старта.
Подготовить каталог
В пустом каталоге выполните npm init -y, затем установите закреплённые версии. Сохраняйте код с указанными именами .mjs: настройка ESM в package.json не требуется.
npm install @swarmmachina/swm-core@5.2.3 @swarmmachina/swm-logs@0.1.1JSON API с CORS
CORS-helper вызывается до чтения body. При OPTIONS он отвечает на preflight и возвращает true; обычный POST получает CORS-заголовки и JSON-ответ.
Второй терминал: preflight должен вернуть 204, POST вернёт {"received":{"ok":true}}. Разрешён конкретный origin https://app.example. CORS задаёт доступ браузера к ответу; проверку пользователя нужно реализовать отдельно.
import Server, { cors } from '@swarmmachina/swm-core'
const applyCors = cors({
origin: 'https://app.example',
methods: ['POST', 'OPTIONS'],
allowedHeaders: ['content-type'],
maxAge: 600
})
const server = new Server({
host: '127.0.0.1',
port: 3000,
ws: null,
http: {
maxBodySize: 64 * 1024,
maxBodyBudget: 8 * 1024 * 1024,
routes: [
{
method: 'any',
path: '/api/echo',
handler: async (ctx) => {
if (applyCors(ctx)) return
if (ctx.getMethod() !== 'post') {
ctx.setStatus(405)
return { error: 'Method not allowed' }
}
return { received: await ctx.json() }
}
}
]
}
})
await server.listen()node json-cors.mjs
# Второй терминал:
curl -i -X OPTIONS http://127.0.0.1:3000/api/echo \
-H 'origin: https://app.example' \
-H 'access-control-request-method: POST' \
-H 'access-control-request-headers: content-type'
curl --fail http://127.0.0.1:3000/api/echo \
-H 'origin: https://app.example' \
-H 'content-type: application/json' --data '{"ok":true}'Проверка WebSocket upgrade
Статический DEMO_TOKEN показывает место проверки серверного клиента. Отсутствующий токен не позволяет запустить пример; неверный токен отклоняет upgrade. Заголовок authorization явно сохраняется через prefetchHeaders.
curl проверяет handshake: с правильным токеном ожидается 101 Switching Protocols, без authorization вернётся 403. После успешного upgrade curl завершится по --max-time: соединение остаётся открытым.
Браузерный WebSocket API не позволяет задать произвольный Authorization-заголовок. Для браузера используйте свою сессию и проверку Origin. Замените демонстрационное сравнение реальной аутентификацией перед сетевым использованием.
import Server from '@swarmmachina/swm-core'
const token = process.env.DEMO_TOKEN
if (!token) throw new Error('Set DEMO_TOKEN before starting the example')
const server = new Server({
host: '127.0.0.1',
port: 3000,
http: null,
ws: {
prefetchHeaders: ['authorization'],
upgradeTimeoutMs: 5_000,
maxPayloadLength: 16 * 1024,
maxBackpressure: 64 * 1024,
closeOnBackpressureLimit: true,
onUpgrade: (meta) => {
if (meta.url() !== '/ws') return null
return meta.headers.authorization === `Bearer ${token}` ? { role: 'demo' } : null
},
onMessage: (ctx, message) => ctx.send(ctx.decode(message))
}
})
await server.listen()DEMO_TOKEN=local-demo node websocket-auth.mjs
# Второй терминал:
curl --http1.1 --max-time 2 -i http://127.0.0.1:3000/ws \
-H 'connection: Upgrade' -H 'upgrade: websocket' \
-H 'sec-websocket-version: 13' \
-H 'sec-websocket-key: dGhlIHNhbXBsZSBub25jZQ==' \
-H 'authorization: Bearer local-demo'Потоковый upload в файл
Сохраните оба файла рядом. UploadSink владеет счётчиком активных загрузок: допускает два потока, а лишнему запросу отвечает 503. Каждый файл получает случайное имя; при ошибке частичный файл удаляется.
bodyStream() создаётся до первого await и передаётся в pipeline(). prefetch выключен, один upload ограничен 8 МиБ. Проверка вернёт 201 и id сохранённого файла в ./uploads.
Streaming обходит maxBodyBudget. Лимит параллелизма относится только к этому процессу; общий объём хранилища, квоты пользователя и очистку успешно загруженных файлов нужно задать отдельно.
import { randomUUID } from 'node:crypto'
import { createWriteStream } from 'node:fs'
import { rm } from 'node:fs/promises'
import { join } from 'node:path'
import { pipeline } from 'node:stream/promises'
export default class UploadSink {
#directory
#active = 0
constructor(directory) {
this.#directory = directory
}
async accept(ctx) {
if (this.#active >= 2) {
ctx.setStatus(503)
return { error: 'Upload capacity reached' }
}
const upload = ctx.bodyStream()
const id = randomUUID()
const path = join(this.#directory, id)
this.#active += 1
try {
await pipeline(upload, createWriteStream(path, { flags: 'wx' }))
ctx.setStatus(201)
return { id }
} catch (error) {
await rm(path, { force: true })
throw error
} finally {
this.#active -= 1
}
}
}import { mkdir } from 'node:fs/promises'
import Server from '@swarmmachina/swm-core'
import UploadSink from './upload-sink.mjs'
await mkdir('./uploads', { recursive: true })
const uploads = new UploadSink('./uploads')
const server = new Server({
host: '127.0.0.1',
port: 3000,
ws: null,
http: {
prefetch: false,
maxStreamBodySize: 8 * 1024 * 1024,
routes: [{ method: 'post', path: '/upload', handler: (ctx) => uploads.accept(ctx) }]
}
})
await server.listen()node upload.mjs
# Второй терминал:
curl --fail http://127.0.0.1:3000/upload --data-binary @upload.mjsRequest ID и структурированные логи
Генерируйте requestId на сервере, добавляйте его в child logger и возвращайте через x-request-id. Пример пишет только метод и путь; body, cookies и входящие credentials в логи не попадают.
curl покажет одинаковый requestId в заголовке и JSON-ответе, а терминал сервера выведет NDJSON-запись с тем же значением. redaction настроена для верхнеуровневых authorization и password; вложенные поля требуют собственных путей.
import { randomUUID } from 'node:crypto'
import Server from '@swarmmachina/swm-core'
import Logger from '@swarmmachina/swm-logs'
const logger = new Logger({
bindings: { service: 'api' },
redact: ['authorization', 'password']
})
const server = new Server({
host: '127.0.0.1',
port: 3000,
ws: null,
http: {
onRequest: (ctx) => {
const requestId = randomUUID()
const log = logger.child({ requestId })
ctx.setHeader('x-request-id', requestId)
log.info({ method: ctx.getMethod(), path: ctx.getUrl() }, 'request')
return { requestId }
}
}
})
await server.listen()node request-logging.mjs
# Второй терминал:
curl -i http://127.0.0.1:3000/hello