gravity-ui · dgaponov · Sep 17, 2026 · Sep 17, 2026 · Sep 17, 2026 · Sep 17, 2026
@@ -1,6 +1,6 @@
 # ExpressKit
 
-ExpressKit ist ein leichtgewichtiger [express.js](https://expressjs.com/)-Wrapper, der sich in [NodeKit](https://github.com/gravity-ui/nodekit) integriert und einige nützliche Funktionen bietet, wie z. B. Request-Logging, Tracing-Unterstützung, asynchrone Controller & Middleware und eine detaillierte Routenbeschreibung.
+ExpressKit ist ein leichtgewichtiger [express.js](https://expressjs.com/)-Wrapper, der sich in [NodeKit](https://github.com/gravity-ui/nodekit) integriert und einige nützliche Funktionen wie Request-Logging, Tracing-Unterstützung, asynchrone Controller & Middleware und detaillierte Routenbeschreibungen bietet.
 
 Installation:
 
@@ -25,6 +25,18 @@ const app = new ExpressKit(nodekit, {
 app.run();
 ```
 
+## Eigene Telemetrie
+
+Standardmäßig sendet die eigene Telemetrie die ursprüngliche Request-URL. Anwendungen mit großen oder
+Query-Strings mit hoher Kardinalität können Query-Parameter entfernen, bevor Statistiken gesendet werden:
+
+```typescript
+const config: Partial<AppConfig> = {
+  appTelemetryChEnableSelfStats: true,
+  appTelemetryChSelfStatsStripQueryParams: true,
+};
+```
+
 ## CSP
 
 `config.ts`
@@ -56,7 +68,7 @@ export default config;
 
 ## CSRF-Schutz
 
-ExpressKit bietet integrierten Schutz vor Cross-Site Request Forgery (CSRF), um Ihre Anwendungen vor bösartigen Cross-Origin-Anfragen zu sichern. Die CSRF-Middleware generiert und validiert automatisch Tokens für zustandsändernde HTTP-Anfragen.
+ExpressKit bietet integrierten Schutz vor Cross-Site Request Forgery (CSRF), um Ihre Anwendungen vor bösartigen Cross-Origin-Anfragen zu schützen. Die CSRF-Middleware generiert und validiert automatisch Tokens für zustandsändernde HTTP-Anfragen.
 
 ### Grundlegende Konfiguration
 
@@ -76,11 +88,11 @@ export default config;
 ### Konfigurationsoptionen
 
 | Option              | Typ                 | Standard                              | Beschreibung                                                                                     |
-| ------------------- | ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `appCsrfSecret`     | `string \| string[]` | -                                     | **Erforderlich.** Geheimer Schlüssel/Schlüssel für die HMAC-Token-Generierung. Mehrere Schlüssel ermöglichen die Schlüsselrotation. |
-| `appCsrfLifetime`   | `number`            | `2592000` (30 Tage)                   | Token-Lebensdauer in Sekunden. Setzen Sie auf `0` für kein Ablaufdatum.                                        |
-| `appCsrfHeaderName` | `string`            | `'x-csrf-token'`                      | Name des HTTP-Headers für die Token-Validierung.                                                          |
-| `appCsrfMethods`    | `string[]`          | `['POST', 'PUT', 'DELETE', 'PATCH']` | HTTP-Methoden, die eine CSRF-Validierung erfordern.                                                      |
+| ------------------- | -------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `appCsrfSecret`     | `string \| string[]` | -                                    | **Erforderlich.** Geheimer Schlüssel (oder Schlüssel) für die HMAC-Token-Generierung. Mehrere Schlüssel ermöglichen die Schlüsselrotation. |
+| `appCsrfLifetime`   | `number`             | `2592000` (30 Tage)                  | Token-Lebensdauer in Sekunden. Setzen Sie auf `0` für kein Ablaufdatum.                                        |
+| `appCsrfHeaderName` | `string`             | `'x-csrf-token'`                     | Name des HTTP-Headers für die Token-Validierung.                                                          |
+| `appCsrfMethods`    | `string[]`           | `['POST', 'PUT', 'DELETE', 'PATCH']` | HTTP-Methoden, die eine CSRF-Validierung erfordern.                                                      |
 
 ### Verwendung
 
@@ -109,7 +121,7 @@ const app = new ExpressKit(nodekit, {
 
   'POST /api/submit': (req, res) => {
     // Diese Route validiert automatisch das CSRF-Token
-    res.json({message: 'Formular erfolgreich gesendet'});
+    res.json({message: 'Formular erfolgreich übermittelt'});
   },
 });
 ```
@@ -138,7 +150,7 @@ Standardmäßig setzt ExpressKit `no-cache`-Header auf alle Antworten. Sie könn
 
 ```typescript
 const config: Partial<AppConfig> = {
-  expressEnableCaching: true, // Caching standardmäßig zulassen
+  expressEnableCaching: true, // Caching standardmäßig erlauben
 };
 ```
 
@@ -147,11 +159,11 @@ const config: Partial<AppConfig> = {
 ```typescript
 const app = new ExpressKit(nodekit, {
   'GET /api/cached': {
-    enableCaching: true, // Caching für diese Route zulassen
+    enableCaching: true, // Caching für diese Route erlauben
     handler: (req, res) => res.json({data: 'cacheable'}),
   },
   'GET /api/fresh': {
-    enableCaching: false, // no-cache erzwingen
+    enableCaching: false, // No-Cache erzwingen
     handler: (req, res) => res.json({data: 'always fresh'}),
   },
 });
@@ -161,4 +173,4 @@ const app = new ExpressKit(nodekit, {
 
 ## Validierung und Antwortserialisierung
 
-- [Request Validation and Response Serialization](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - Verwenden Sie Zod-Schemas für automatische Request-Validierung und Antwortserialisierung.
+- [Request Validation and Response Serialization](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - nutze Zod-Schemas für automatische Request-Validierung und Response-Serialisierung.
@@ -1,6 +1,6 @@
 # ExpressKit
 
-ExpressKit es un wrapper ligero para [express.js](https://expressjs.com/) que se integra con [NodeKit](https://github.com/gravity-ui/nodekit) y proporciona algunas características útiles como registro de solicitudes, soporte de tracing, controladores y middleware asíncronos, y descripciones detalladas de las rutas.
+ExpressKit es un wrapper ligero para [express.js](https://expressjs.com/) que se integra con [NodeKit](https://github.com/gravity-ui/nodekit) y proporciona algunas características útiles como registro de solicitudes, soporte de tracing, controladores y middleware asíncronos, y descripciones detalladas de rutas.
 
 Instalación:
 
@@ -25,6 +25,17 @@ const app = new ExpressKit(nodekit, {
 app.run();
 ```
 
+## Telemetría propia
+
+Por defecto, la telemetría propia envía la URL de la solicitud original. Las aplicaciones con cadenas de consulta grandes o de alta cardinalidad pueden eliminar los parámetros de consulta antes de enviar las estadísticas:
+
+```typescript
+const config: Partial<AppConfig> = {
+  appTelemetryChEnableSelfStats: true,
+  appTelemetryChSelfStatsStripQueryParams: true,
+};
+```
+
 ## CSP
 
 `config.ts`
@@ -95,8 +106,8 @@ const nodekit = new NodeKit({
     appCsrfSecret: 'tu-clave-secreta',
     appAuthPolicy: AuthPolicy.required,
 
-    // Asegúrate de que tu middleware establezca el ID de usuario en originalContext, de lo contrario, la generación del token CSRF fallará
-    appAuthHandler: tuManejadorDeAutenticacion,
+    // Asegúrate de que tu middleware establezca el ID de usuario en el originalContext, de lo contrario, la generación del token CSRF fallará
+    appAuthHandler: yourAuthHandler,
   },
 });
 
@@ -160,4 +171,4 @@ El `enableCaching` a nivel de ruta anula la configuración global. El estado de
 
 ## Validación y serialización de respuestas
 
-- [Validación de solicitudes y serialización de respuestas](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - utiliza esquemas Zod para la validación automática de solicitudes y la serialización de respuestas.
+- [Validación de Solicitudes y Serialización de Respuestas](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - utiliza esquemas Zod para la validación automática de solicitudes y la serialización de respuestas.
@@ -1,6 +1,6 @@
 # ExpressKit
 
-ExpressKit est un wrapper léger pour [express.js](https://expressjs.com/) qui s'intègre à [NodeKit](https://github.com/gravity-ui/nodekit) et offre des fonctionnalités utiles telles que la journalisation des requêtes, le support du traçage, les contrôleurs et middlewares asynchrones, ainsi qu'une description détaillée des routes.
+ExpressKit est un wrapper léger pour [express.js](https://expressjs.com/) qui s'intègre à [NodeKit](https://github.com/gravity-ui/nodekit) et offre des fonctionnalités utiles telles que la journalisation des requêtes, la prise en charge du traçage, les contrôleurs et middlewares asynchrones, ainsi qu'une description détaillée des routes.
 
 Installation :
 
@@ -25,6 +25,17 @@ const app = new ExpressKit(nodekit, {
 app.run();
 ```
 
+## Télémétrie interne
+
+Par défaut, la télémétrie interne envoie l'URL de la requête d'origine. Les applications avec des chaînes de requête volumineuses ou à haute cardinalité peuvent supprimer les paramètres de requête avant d'envoyer les statistiques :
+
+```typescript
+const config: Partial<AppConfig> = {
+  appTelemetryChEnableSelfStats: true,
+  appTelemetryChSelfStatsStripQueryParams: true,
+};
+```
+
 ## CSP
 
 `config.ts`
@@ -56,7 +67,7 @@ export default config;
 
 ## Protection CSRF
 
-ExpressKit fournit une protection intégrée contre le Cross-Site Request Forgery (CSRF) pour sécuriser vos applications contre les requêtes inter-sites malveillantes. Le middleware CSRF génère et valide automatiquement les jetons pour les requêtes HTTP modifiant l'état.
+ExpressKit fournit une protection intégrée contre les falsifications de requêtes intersites (CSRF) pour sécuriser vos applications contre les requêtes inter-origines malveillantes. Le middleware CSRF génère et valide automatiquement les jetons pour les requêtes HTTP modifiant l'état.
 
 ### Configuration de base
 
@@ -78,7 +89,7 @@ export default config;
 | Option              | Type                 | Défaut                              | Description                                                                                     |
 | ------------------- | -------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
 | `appCsrfSecret`     | `string \| string[]` | -                                    | **Requis.** Clé(s) secrète(s) pour la génération de jetons HMAC. Plusieurs secrets permettent la rotation des clés. |
-| `appCsrfLifetime`   | `number`             | `2592000` (30 jours)                  | Durée de vie du jeton en secondes. Définissez à `0` pour aucune expiration.                                        |
+| `appCsrfLifetime`   | `number`             | `2592000` (30 jours)                  | Durée de vie du jeton en secondes. Définir à `0` pour aucune expiration.                                        |
 | `appCsrfHeaderName` | `string`             | `'x-csrf-token'`                     | Nom de l'en-tête HTTP pour la validation du jeton.                                                          |
 | `appCsrfMethods`    | `string[]`           | `['POST', 'PUT', 'DELETE', 'PATCH']` | Méthodes HTTP nécessitant une validation CSRF.                                                      |
 
@@ -158,6 +169,6 @@ const app = new ExpressKit(nodekit, {
 
 Le paramètre `enableCaching` au niveau de la route remplace le réglage global. L'état de la mise en cache est disponible dans `req.routeInfo.enableCaching`.
 
-## Validation et Sérialisation des réponses
+## Validation et sérialisation des réponses
 
 - [Validation des requêtes et sérialisation des réponses](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - utilisez les schémas Zod pour la validation automatique des requêtes et la sérialisation des réponses.
@@ -0,0 +1,174 @@
+# ExpressKit
+
+ExpressKit は、[express.js](https://expressjs.com/) をラップした軽量ライブラリで、[NodeKit](https://github.com/gravity-ui/nodekit) と統合されており、リクエストロギング、トレーシングサポート、非同期コントローラーとミドルウェア、詳細なルート説明などの便利な機能を提供します。
+
+インストール:
+
+```bash
+npm install --save @gravity-ui/nodekit @gravity-ui/expresskit
+```
+
+基本的な使い方:
+
+```typescript
+import {ExpressKit} from '@gravity-ui/expresskit';
+import {NodeKit} from '@gravity-ui/nodekit';
+
+const nodekit = new NodeKit();
+
+const app = new ExpressKit(nodekit, {
+  'GET /': (req, res) => {
+    res.send('Hello World!');
+  },
+});
+
+app.run();
+```
+
+## セルフテレメトリ
+
+デフォルトでは、セルフテレメトリは元のリクエスト URL を送信します。クエリ文字列が大きい、またはカーディナリティが高いアプリケーションでは、統計情報を送信する前にクエリパラメータを削除できます。
+
+```typescript
+const config: Partial<AppConfig> = {
+  appTelemetryChEnableSelfStats: true,
+  appTelemetryChSelfStatsStripQueryParams: true,
+};
+```
+
+## CSP
+
+`config.ts`
+
+```typescript
+import type {AppConfig} from '@gravity-ui/nodekit';
+import {csp} from '@gravity-ui/expresskit';
+
+const config: Partial<AppConfig> = {
+    expressCspEnable: true,
+    expressCspPresets: ({getDefaultPresets}) => {
+        return getDefaultPresets({defaultNone: true}).concat([
+            csp.inline(),
+            {csp.directives.REPORT_TO: 'my-report-group'},
+        ]);
+    },
+    expressCspReportTo: [
+        {
+            group: 'my-report-group',
+            max_age: 30 * 60,
+            endpoints: [{ url: 'https://cspreport.com/send'}],
+            include_subdomains: true,
+        }
+    ]
+}
+
+export default config;
+```
+
+## CSRF 保護
+
+ExpressKit は、アプリケーションを悪意のあるクロスオリジンリクエストから保護するために、クロスサイトリクエストフォージェリ (CSRF) 保護を組み込んでいます。CSRF ミドルウェアは、状態を変更する HTTP リクエストのトークンを自動的に生成および検証します。
+
+### 基本設定
+
+CSRF 保護を有効にするには、設定でシークレットキーを設定します。
+
+```typescript
+import type {AppConfig} from '@gravity-ui/nodekit';
+
+const config: Partial<AppConfig> = {
+  // ...
+  appCsrfSecret: 'your-secret-key-here',
+};
+
+export default config;
+```
+
+### 設定オプション
+
+| オプション              | タイプ                 | デフォルト                              | 説明                                                                                     |
+| ------------------- | -------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `appCsrfSecret`     | `string \| string[]` | -                                    | **必須。** HMAC トークン生成用のシークレットキー。複数のシークレットでキーローテーションが可能です。 |
+| `appCsrfLifetime`   | `number`             | `2592000` (30 日)                  | トークンの有効期間 (秒)。`0` に設定すると有効期限なしになります。                                        |
+| `appCsrfHeaderName` | `string`             | `'x-csrf-token'`                     | トークン検証用の HTTP ヘッダー名。                                                          |
+| `appCsrfMethods`    | `string[]`           | `['POST', 'PUT', 'DELETE', 'PATCH']` | CSRF 検証が必要な HTTP メソッド。                                                      |
+
+### 使用方法
+
+設定後、CSRF 保護は指定された HTTP メソッドを持つすべてのルートに自動的に適用されます。
+
+```typescript
+import {ExpressKit, AuthPolicy} from '@gravity-ui/expresskit';
+import {NodeKit} from '@gravity-ui/nodekit';
+
+const nodekit = new NodeKit({
+  config: {
+    appCsrfSecret: 'your-secret-key',
+    appAuthPolicy: AuthPolicy.required,
+
+    // ミドルウェアが originalContext にユーザー ID を設定していることを確認してください。そうしないと、CSRF トークン生成が失敗します。
+    appAuthHandler: yourAuthHandler,
+  },
+});
+
+const app = new ExpressKit(nodekit, {
+  'GET /api/form': (req, res) => {
+    // トークンはリクエストコンテキストで利用可能です
+    res.json({csrfToken: req.originalContext.get('csrfToken')});
+  },
+
+  'POST /api/submit': (req, res) => {
+    // このルートは CSRF トークンを自動的に検証します
+    res.json({message: 'Form submitted successfully'});
+  },
+});
+```
+
+### ルートごとの設定
+
+特定のルートで CSRF 保護を無効にすることができます。
+
+```typescript
+const app = new ExpressKit(nodekit, {
+  'POST /api/webhook': {
+    authPolicy: AuthPolicy.required,
+    disableCsrf: true, // このルートの CSRF を無効にする
+    handler: (req, res) => {
+      res.json({message: 'Webhook processed'});
+    },
+  },
+});
+```
+
+## キャッシュ制御
+
+デフォルトでは、ExpressKit はすべてのレスポンスに `no-cache` ヘッダーを設定します。この動作はグローバルまたはルートごとに制御できます。
+
+### グローバル設定
+
+```typescript
+const config: Partial<AppConfig> = {
+  expressEnableCaching: true, // デフォルトでキャッシュを許可する
+};
+```
+
+### ルートごとの設定
+
+```typescript
+const app = new ExpressKit(nodekit, {
+  'GET /api/cached': {
+    enableCaching: true, // このルートのキャッシュを許可する
+    handler: (req, res) => res.json({data: 'cacheable'}),
+  },
+  'GET /api/fresh': {
+    enableCaching: false, // no-cache を強制する
+    handler: (req, res) => res.json({data: 'always fresh'}),
+  },
+});
+```
+
+ルートレベルの `enableCaching` はグローバル設定を上書きします。キャッシュの状態は `req.routeInfo.enableCaching` で利用可能です。
+
+## 検証とレスポンスシリアライゼーション
+
+- [リクエストバリデーションとレスポンスシリアライゼーション](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - Zodスキーマを使用して、リクエストのバリデーションとレスポンスのシリアライゼーションを自動化します。