@etc-utils/typespec-amqp-ws 1.0.0

package/docs/usage.md

@@ -0,0 +1,281 @@
+# Использование `@etc-utils/typespec-amqp-ws`
+
+## Установка
+
+```bash
+npm install -D @etc-utils/typespec-amqp-ws @typespec/compiler @typespec/asset-emitter
+```
+
+Требования:
+- Node.js 22+ (рекомендуется 24+ для совместимости с `@asyncapi/cli`)
+- TypeSpec 1.12+
+
+## Конфигурация
+
+В корне папки с TypeSpec-описанием сервиса (например, `<service>/asyncapi/`) создаётся файл `tspconfig.yaml`. Эмиттер `@etc-utils/typespec-amqp-ws` имеет два emit-таргета: `/amqp` и `/ws`. Один проект использует **один** из них.
+
+### Конфиг для AMQP-сервиса
+
+```yaml
+emit:
+  - "@etc-utils/typespec-amqp-ws/amqp"
+options:
+  "@etc-utils/typespec-amqp-ws/amqp":
+    file-type: yaml          # yaml (default) или json
+    output-file: "asyncapi.yaml"
+    new-line: "lf"           # lf (default) или crlf
+output-dir: "{project-root}/tsp-output"
+```
+
+### Конфиг для WebSocket-сервиса
+
+```yaml
+emit:
+  - "@etc-utils/typespec-amqp-ws/ws"
+options:
+  "@etc-utils/typespec-amqp-ws/ws":
+    file-type: yaml
+    output-file: "asyncapi.yaml"
+    new-line: "lf"
+output-dir: "{project-root}/tsp-output"
+```
+
+После компиляции (`tsp compile .`) сгенерированный YAML лежит в `tsp-output/@etc-utils/typespec-amqp-ws/asyncapi.yaml`. Дальнейший пайплайн (redocly lint, modelina codegen, документация) идёт от этого файла.
+
+## Структура проекта
+
+Рекомендованная (соответствует тому, как у нас в команде):
+
+```
+<service>/asyncapi/
+├── main.tsp                     # @service / @info / @server + операции
+├── tsp-components/
+│   └── models.tsp               # scalars + enums + модели
+├── tspconfig.yaml               # конфиг эмиттера
+├── package.json                 # зависимости (typespec, asset-emitter)
+├── redocly.yaml                 # конфиг линтера
+└── Makefile                     # include шаблонного build pipeline
+```
+
+## API эмиттера
+
+### Декораторы общего назначения (namespace `TspAsyncApi`)
+
+| Декоратор | Применяется к | Что делает |
+|---|---|---|
+| `@service(#{title})` | namespace | Стандартный из `@typespec/compiler`. Маркирует namespace как корневой сервис. |
+| `@info(#{...})` | namespace | Заполняет блок `info:` AsyncAPI. Поля: `version`, `description?`, `contact?{name?, url?, email?}`, `license?{name, url?}`, `externalDocs?{url, description?}` |
+| `@server(name, #{...})` | namespace | Описывает один сервер (брокер). Поля: `host`, `protocol`, `pathname?`, `description?`, `variables?: Record<#{default?, description?, enum?}>` |
+
+### Декораторы AMQP (namespace `TspAsyncApi.Amqp`)
+
+| Декоратор | Применяется к | Описание |
+|---|---|---|
+| `@publish(#{...})` | op | Операция-publisher → `action: send`. Поля: `channelName?`, `routingKey?`, `exchange: #{name, type: "direct"\|"fanout", durable?, autoDelete?}` |
+| `@consume(#{...})` | op | Операция-consumer → `action: receive`. Поля: `channelName?`, `routingKey?`, `queue: #{name, durable?, autoDelete?, exclusive?}` |
+| `@message(#{...})` | op | Override параметров сообщения: `name?`, `summary?` |
+
+### Декораторы WebSocket (namespace `TspAsyncApi.WebSocket`)
+
+| Декоратор | Применяется к | Описание |
+|---|---|---|
+| `@publish` | op | без аргументов → `action: send` |
+| `@consume` | op | без аргументов → `action: receive` |
+| `@reply(MessageModel)` | op | Модель ответного сообщения (request/reply pattern). Reply-сообщение автоматически добавится в канал и `components.messages`. |
+| `@binary` | op | Помечает сообщение бинарным → `contentType: application/octet-stream` |
+| `@message(#{...})` | op | Override параметров сообщения |
+
+### Стандартные TypeSpec-декораторы
+
+Из `@typespec/compiler`:
+- `@doc("...")` — длинное описание (попадает в `description` YAML)
+- `@summary("...")` — короткое summary (попадает в `summary` YAML)
+
+## Поддерживаемые TypeSpec-типы
+
+| TypeSpec | YAML | Go / TS / C++ |
+|---|---|---|
+| `string` | `{type: string}` | string / string / std::string |
+| `boolean` | `{type: boolean}` | bool / boolean / bool |
+| `integer` | `{type: integer}` | int32 / number / int |
+| `bytes` | `{type: string, format: binary}` | []byte / Uint8Array / std::vector<uint8_t> |
+| `enum X { A, B }` | `{type: string, enum: [A, B]}` | string-typedef с константами |
+| `scalar X extends string` | `{type: string}` в `components.schemas.X` | именованный string-typedef |
+| `model X { ... }` | `{type: object, properties, required, additionalProperties: false}` | сгенерированная структура |
+| `T[]` | `{type: array, items: <T>}` | slice / array |
+| `Record<T>` | `{type: object, additionalProperties: <T>}` | `map[string]T` / `Record<string, T>` |
+| literal `"foo"` (на поле модели) | `{type: string, const: "foo"}` | const-значение |
+| `T \| null` | `{type: [<base>, null]}` | pointer / nullable |
+| `field?: T` | поле не в `required` | optional |
+
+## Запрещённые типы (ошибка компиляции)
+
+Эмиттер намеренно **запрещает**:
+
+| Тип | Почему |
+|---|---|
+| `int8`/`int16`/`int32`, `uint8`/`uint16`/`uint32` | Кодгенераторы (`modelina`, `openapi-generator-cli`) **игнорируют** ширину и signed/unsigned, генерируют `int32`/`number`. Размер-специфичные типы создают ложное ожидание сохранения семантики на границе между языками. |
+| `int64`/`uint64` | 64-битные числа должны передаваться как `string` — JavaScript не умеет точно представлять 64-битные числа в JSON. Поясните формат в `@doc`. |
+| `float32`/`float64`/`decimal`/`decimal128` | Числа с плавающей точкой передавайте через `string` во избежание потерь точности на границе между языками. |
+| `safeint`/`numeric` | Неоднозначно для кодогенерации. Используйте `integer`. |
+| `utcDateTime`/`plainDate`/`plainTime`/`duration` | Дата/время — это `string` в RFC-3339 с пояснением в `@doc`. TypeScript-кодген иначе подставляет `Date`, что ломает разбор в разных локалях. |
+| `url` | URL — это `string`. |
+
+Эмиттер также **запрещает анонимные inline-модели в полях**:
+
+```typespec
+// ❌ Ошибка эмиттера
+model M {
+  payload: { foo: string };
+}
+
+// ✅ Только через явно объявленную модель
+model MPayload { foo: string; }
+model M { payload: MPayload; }
+```
+
+Обоснование: детерминированные имена в выводе важнее лаконичности на стороне источника. modelina требует осмысленных имён для генерации Go/TS-типов; авто-генерация ненадёжна.
+
+## Полный пример: AMQP-сервис
+
+```typespec
+import "@etc-utils/typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "Notifications" })
+@info(#{
+  version: "1.0.0",
+  description: "Сервис рассылки уведомлений через RabbitMQ",
+})
+@server("rabbit", #{
+  host: "rabbit.example.com:5672",
+  pathname: "/notifications",
+  protocol: "amqp",
+  description: "RabbitMQ-сервер",
+})
+namespace Notifications;
+
+@doc("Уведомление пользователю")
+model Notification {
+  @doc("Идентификатор уведомления")
+  notificationId: string;
+
+  @doc("Текст уведомления")
+  text: string;
+}
+
+@publish(#{
+  routingKey: "notifications.created",
+  exchange: #{
+    name: "notifications-exchange",
+    type: "direct",
+    durable: true,
+  },
+})
+@summary("Опубликовать новое уведомление")
+op sendNotification(): Notification;
+
+@consume(#{
+  routingKey: "notifications.acknowledge",
+  queue: #{
+    name: "notifications-ack-queue",
+    durable: true,
+    autoDelete: false,
+  },
+})
+@summary("Обработать подтверждение доставки")
+op handleAck(): Notification;
+```
+
+## Полный пример: WebSocket с дискриминатором и reply
+
+```typespec
+import "@etc-utils/typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.WebSocket;
+
+@service(#{ title: "Chat WS" })
+@info(#{ version: "1.0.0" })
+@server("public", #{
+  host: "localhost:{port}",
+  protocol: "ws",
+  pathname: "/chat",
+  variables: #{
+    port: #{ `default`: "8080", description: "Порт WS-сервера" },
+  },
+})
+namespace Chat;
+
+// Дискриминатор сообщения — обычное поле literal-типа.
+// Эмиттер выведет {type: "string", const: "userJoined"} в JSON Schema.
+model UserJoined {
+  eventType: "userJoined";
+  msgUid: string;
+  userId: string;
+  nickname: string;
+}
+
+model SendMessage {
+  eventType: "sendMessage";
+  msgUid: string;
+  text: string;
+}
+
+model SendMessageResponse {
+  eventType: "sendMessageResponse";
+  msgUid: string;
+  ok: boolean;
+}
+
+// Receive
+@consume
+@summary("Пользователь подключился к чату")
+op userJoined(): UserJoined;
+
+// Send + reply (request/reply pattern)
+@publish
+@reply(SendMessageResponse)
+@summary("Отправить сообщение в чат")
+op sendMessage(): SendMessage;
+```
+
+Все WS-операции автоматически складываются на единый канал `/`. Это типичный паттерн WebSocket-API, где дискриминация сообщений происходит через поле `eventType`.
+
+## Версионирование AsyncAPI
+
+Эмиттер генерирует AsyncAPI 3.0.0. Версия 3.1 backward-совместима, но мы остаёмся на 3.0 ради консервативности и максимальной совместимости с `modelina`/`redocly`.
+
+## Дискриминация сообщений в WebSocket
+
+В TypeSpec литерал-типы (`"localActions"`) превращаются в JSON Schema `const` — нативный механизм без специальных декораторов. **Любое** поле модели типа `: "значение"` становится `const` в схеме. Поле может называться как угодно — `eventType`, `kind`, `type`, и т.д. Модели без таких полей тоже валидны (например, AMQP-сообщения обычно без дискриминатора).
+
+## Диагностики
+
+Эмиттер выдаёт следующие коды (все с префиксом `@etc-utils/typespec-amqp-ws/`):
+
+- `unsupported-sized-int`, `unsupported-int64`, `unsupported-float`, `unsupported-fuzzy-numeric`, `unsupported-temporal`, `unsupported-url` — попытка использовать запрещённый тип.
+- `anonymous-model`, `anonymous-return` — анонимная inline-модель в поле или return type.
+- `non-string-enum`, `invalid-enum-value` — некорректный enum (numeric или не-идентификаторное значение).
+- `unknown-exchange-type` — `topic` или `headers` exchange (вне scope).
+- `unsupported-union` — union, не являющийся `T | null`.
+- `missing-doc` (warning) — модель/enum без `@doc`.
+
+## Out of scope (v1)
+
+Намеренно **не реализовано** в v1 — добавляется по запросу при реальной потребности:
+
+- Транспорты Kafka, MQTT, HTTP/SSE, SNS/SQS.
+- Exchange types `topic`, `headers`.
+- AsyncAPI security schemes.
+- `correlationId`.
+- Traits (`channelTraits`, `operationTraits`, `messageTraits`).
+- AsyncAPI extensions (`x-` properties).
+- Polymorphism: пользовательские `oneOf`/`anyOf`/`allOf` (внутренний `allOf` для $ref+description — используется автоматически).
+- TypeSpec `@versioned` интеграция.
+- Numeric-валуированные enum.
+- `@tag` на operations.
+- AsyncAPI 3.1.
+- JSON output (только YAML).

package/examples/amqp-consume.tsp

@@ -0,0 +1,26 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "Notifications Consumer" })
+@info(#{ version: "1.0.0" })
+@server("rabbit", #{ host: "localhost:5672", protocol: "amqp" })
+namespace NotificationsConsumer;
+
+@doc("Уведомление пользователю")
+model Notification {
+  notificationId: string;
+  text: string;
+}
+
+@consume(#{
+  routingKey: "notifications.created",
+  queue: #{
+    name: "notifications-consumer-queue",
+    durable: true,
+    autoDelete: false,
+  },
+})
+@summary("Обработать уведомление из очереди")
+op handleNotification(): Notification;

package/examples/amqp-publish.tsp

@@ -0,0 +1,25 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "Notifications Producer" })
+@info(#{ version: "1.0.0" })
+@server("rabbit", #{ host: "localhost:5672", protocol: "amqp" })
+namespace NotificationsProducer;
+
+@doc("Уведомление пользователю")
+model Notification {
+  @doc("Уникальный идентификатор уведомления")
+  notificationId: string;
+
+  @doc("Текст уведомления")
+  text: string;
+}
+
+@publish(#{
+  routingKey: "notifications.created",
+  exchange: #{ name: "notifications-exchange", type: "direct", durable: true },
+})
+@summary("Опубликовать новое уведомление")
+op sendNotification(): Notification;

package/examples/ws-discriminator.tsp

@@ -0,0 +1,26 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.WebSocket;
+
+@service(#{ title: "Chat WS" })
+@info(#{ version: "1.0.0" })
+@server("public", #{ host: "localhost:8080", protocol: "ws", pathname: "/ws" })
+namespace Chat;
+
+model UserJoinedPayload { userId: string; nickname: string; }
+model MessagePayload { from: string; text: string; }
+
+// Дискриминатор через literal-тип — никаких специальных декораторов.
+model UserJoined {
+  eventType: "userJoined";
+  payload: UserJoinedPayload;
+}
+
+model NewMessage {
+  eventType: "newMessage";
+  payload: MessagePayload;
+}
+
+@consume op userJoined(): UserJoined;
+@consume op newMessage(): NewMessage;

package/examples/ws-reply.tsp

@@ -0,0 +1,29 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.WebSocket;
+
+@service(#{ title: "Auth WS" })
+@info(#{ version: "1.0.0" })
+@server("public", #{ host: "localhost:8080", protocol: "ws", pathname: "/ws" })
+namespace Auth;
+
+model LoginRequestPayload { username: string; password: string; }
+model LoginResponsePayload { ok: boolean; token?: string; }
+
+model LoginRequest {
+  eventType: "loginRequest";
+  msgUid: string;
+  payload: LoginRequestPayload;
+}
+
+model LoginResponse {
+  eventType: "loginResponse";
+  msgUid: string;
+  payload: LoginResponsePayload;
+}
+
+@publish
+@reply(LoginResponse)
+@summary("Запрос на аутентификацию")
+op login(): LoginRequest;

package/lib/amqp.tsp

@@ -0,0 +1,83 @@
+import "../dist/src/amqp/decorators.js";
+
+using TypeSpec.Reflection;
+
+namespace TspAsyncApi.Amqp;
+
+@doc("Конфиг AMQP-обменника (exchange)")
+model ExchangeConfig {
+  @doc("Имя exchange в RabbitMQ")
+  name: string;
+
+  @doc("Тип exchange: direct либо fanout")
+  type: string;
+
+  @doc("Переживает рестарт брокера")
+  durable?: boolean;
+
+  @doc("Удаляется когда последний биндинг отвалился")
+  autoDelete?: boolean;
+}
+
+@doc("Конфиг AMQP-очереди (queue)")
+model QueueConfig {
+  @doc("Имя очереди в RabbitMQ")
+  name: string;
+
+  @doc("Переживает рестарт брокера")
+  durable?: boolean;
+
+  @doc("Удаляется когда последний consumer отвалился")
+  autoDelete?: boolean;
+
+  @doc("Эксклюзивная — только один consumer")
+  exclusive?: boolean;
+}
+
+@doc("Конфиг операции-publisher (action: send)")
+model PublishConfig {
+  @doc("Имя канала в YAML (override). Default — имя операции верзатим")
+  channelName?: string;
+
+  @doc("Routing key. Может быть опущен для fanout exchange")
+  routingKey?: string;
+
+  @doc("Exchange, в который публикуется сообщение")
+  exchange: ExchangeConfig;
+}
+
+@doc("Конфиг операции-consumer (action: receive)")
+model ConsumeConfig {
+  @doc("Имя канала в YAML (override)")
+  channelName?: string;
+
+  @doc("Routing key (биндинг очереди к exchange)")
+  routingKey?: string;
+
+  @doc("Очередь, из которой читаются сообщения")
+  queue: QueueConfig;
+}
+
+@doc("Override параметров сообщения")
+model MessageOverride {
+  @doc("Имя ключа сообщения в YAML")
+  name?: string;
+
+  @doc("Краткое описание сообщения")
+  summary?: string;
+}
+
+/**
+ * Операция-publisher: сервис отправляет сообщение в exchange.
+ * → AsyncAPI action: send.
+ */
+extern dec publish(target: Operation, config: valueof PublishConfig);
+
+/**
+ * Операция-consumer: сервис читает сообщения из очереди.
+ * → AsyncAPI action: receive.
+ */
+extern dec consume(target: Operation, config: valueof ConsumeConfig);
+
+/** Override параметров сообщения, выводимого эмиттером */
+extern dec message(target: Operation, config: valueof MessageOverride);

package/lib/main.tsp

@@ -0,0 +1,65 @@
+import "../dist/src/index.js";
+import "../dist/src/shared/decorators-service.js";
+
+import "./amqp.tsp";
+import "./ws.tsp";
+
+using TypeSpec.Reflection;
+
+namespace TspAsyncApi;
+
+@doc("Контактные данные владельца API")
+model ContactInfo {
+  name?: string;
+  url?: string;
+  email?: string;
+}
+
+@doc("Лицензия API")
+model LicenseInfo {
+  name: string;
+  url?: string;
+}
+
+@doc("Ссылка на внешнюю документацию")
+model ExternalDocs {
+  url: string;
+  description?: string;
+}
+
+@doc("Блок info AsyncAPI документа")
+model InfoConfig {
+  version: string;
+  description?: string;
+  contact?: ContactInfo;
+  license?: LicenseInfo;
+  externalDocs?: ExternalDocs;
+}
+
+@doc("Переменная в шаблоне URL сервера (например, {port})")
+model ServerVariable {
+  `default`?: string;
+  description?: string;
+  `enum`?: string[];
+}
+
+@doc("Описание сервера (брокера). Соответствует одному ключу в servers AsyncAPI")
+model ServerConfig {
+  host: string;
+  protocol: string;
+  pathname?: string;
+  description?: string;
+  variables?: Record<ServerVariable>;
+}
+
+/**
+ * Заполняет блок info AsyncAPI документа.
+ * Применяется к корневому namespace сервиса (тому же, к которому @service).
+ */
+extern dec info(target: Namespace, options: valueof InfoConfig);
+
+/**
+ * Добавляет одну запись в блок servers AsyncAPI документа.
+ * Можно вызывать многократно для нескольких серверов.
+ */
+extern dec server(target: Namespace, name: valueof string, options: valueof ServerConfig);

package/lib/ws.tsp

@@ -0,0 +1,42 @@
+import "../dist/src/ws/decorators.js";
+
+using TypeSpec.Reflection;
+
+namespace TspAsyncApi.WebSocket;
+
+@doc("Override параметров сообщения")
+model MessageOverride {
+  @doc("Имя ключа сообщения в YAML")
+  name?: string;
+
+  @doc("Краткое описание сообщения")
+  summary?: string;
+}
+
+/**
+ * Операция-publisher: сервис отправляет сообщение.
+ * → AsyncAPI action: send.
+ * Все WS-операции по умолчанию на канале "/".
+ */
+extern dec publish(target: Operation);
+
+/**
+ * Операция-consumer: сервис принимает сообщение.
+ * → AsyncAPI action: receive.
+ */
+extern dec consume(target: Operation);
+
+/**
+ * Указывает модель ответного сообщения (request/reply pattern).
+ * Реплай-сообщение автоматически добавится в канал и components.messages.
+ */
+extern dec reply(target: Operation, replyType: Model);
+
+/**
+ * Помечает сообщение операции как бинарное.
+ * → components.messages.X.contentType: application/octet-stream
+ */
+extern dec binary(target: Operation);
+
+/** Override параметров сообщения */
+extern dec message(target: Operation, config: valueof MessageOverride);

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@etc-utils/typespec-amqp-ws",
+  "version": "1.0.0",
+  "description": "TypeSpec emitter for AsyncAPI 3.0 covering AMQP (RabbitMQ) and WebSocket transports",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TertiumOrganum1/typespec-amqp-ws.git"
+  },
+  "homepage": "https://github.com/TertiumOrganum1/typespec-amqp-ws#readme",
+  "bugs": {
+    "url": "https://github.com/TertiumOrganum1/typespec-amqp-ws/issues"
+  },
+  "keywords": [
+    "typespec",
+    "asyncapi",
+    "amqp",
+    "rabbitmq",
+    "websocket",
+    "emitter"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./amqp": {
+      "import": "./dist/src/amqp/index.js",
+      "types": "./dist/src/amqp/index.d.ts"
+    },
+    "./ws": {
+      "import": "./dist/src/ws/index.js",
+      "types": "./dist/src/ws/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/src/testing.js",
+      "types": "./dist/src/testing.d.ts"
+    }
+  },
+  "tspMain": "./lib/main.tsp",
+  "scripts": {
+    "build": "tsc -b",
+    "watch": "tsc -b --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist coverage *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@typespec/compiler": "^1.12.0",
+    "@typespec/asset-emitter": "^0.79.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@typespec/compiler": "^1.12.0",
+    "@typespec/asset-emitter": "^0.79.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "files": [
+    "dist/src/**",
+    "lib/**",
+    "docs/**",
+    "examples/**",
+    "README.md",
+    "LICENSE"
+  ]
+}