Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(dev-guide): drop forwardRef and request-id interceptor advice
Yudhi Armyndharis3d8a07ce3c70
diff --git a/docs/08-development-guidelines.md b/docs/08-development-guidelines.mdindex ecf047686..fd3161917 100644--- a/docs/08-development-guidelines.md+++ b/docs/08-development-guidelines.md@@ -148,7 +148,7 @@ export class ExampleModule {}```typescript// modules/example/example.controller.ts-import { Controller, Get, Post, Body, Headers, Param, Delete, HttpCode, HttpStatus } from '@nestjs/common';+import { Controller, Get, Post, Body, Param, Delete, HttpCode, HttpStatus } from '@nestjs/common';import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';import { ExampleService } from './example.service';import { CreateExampleDto } from './dto/create-example.dto';@@ -163,11 +163,8 @@ export class ExampleController {@HttpCode(HttpStatus.CREATED)@ApiOperation({ summary: 'Create example' })@ApiResponse({ status: 201, type: ExampleResponseDto })- async create(- @Body() dto: CreateExampleDto,- @Headers('x-request-id') requestId?: string,- ): Promise<ExampleResponseDto> {- return this.exampleService.create(dto, { requestId });+ async create(@Body() dto: CreateExampleDto): Promise<ExampleResponseDto> {+ return this.exampleService.create(dto);}@Get(':id')@@ -213,7 +210,8 @@ export class ExampleService {```typescript// modules/example/example.service.ts-import { Injectable, NotFoundException, Logger } from '@nestjs/common';+import { Injectable, NotFoundException } from '@nestjs/common';+import { createLogger } from '../../common/services/logger.service';import { ExampleRepository } from './example.repository';import { CreateExampleDto } from './dto/create-example.dto';import { Example } from './entities/example.entity';@@ -224,8 +222,8 @@ export class ExampleService {constructor(private readonly repository: ExampleRepository) {}- async create(dto: CreateExampleDto, context?: { requestId?: string }): Promise<Example> {- this.logger.log(`Creating example: ${dto.name}`, context);+ async create(dto: CreateExampleDto): Promise<Example> {+ this.logger.log(`Creating example: ${dto.name}`);const example = this.repository.create(dto);return this.repository.save(example);@@ -796,28 +794,22 @@ ENABLE_SWAGGER=false```typescript// Use createLogger from the shared LoggerService, not console.*-import { Inject, Scope } from '@nestjs/common';-import { REQUEST } from '@nestjs/core';-import { Request } from 'express';+import { Injectable } from '@nestjs/common';import { createLogger } from '../common/services/logger.service';-@Injectable({ scope: Scope.REQUEST })+@Injectable()export class MyService {private readonly logger = createLogger('MyService');- constructor(@Inject(REQUEST) private readonly request: Request) {}-async doSomething(id: string): Promise<void> {- // Log entry with context- const requestId = this.request?.requestId;- this.logger.log(`Processing item`, { id, requestId });+ this.logger.log('Processing item', { id });try {await this.process(id);- this.logger.log(`Item processed successfully`, { id, requestId });+ this.logger.log('Item processed successfully', { id });} catch (error) {// Log error with full stack- this.logger.error(`Failed to process item`, error.stack, { id, requestId });+ this.logger.error('Failed to process item', error instanceof Error ? error.stack : String(error), { id });throw error;}}@@ -825,43 +817,17 @@ export class MyService {```> [!NOTE]-> Propagate `X-Request-ID` from controller to service and include it in all logs for easier cross-component tracing.--### Request ID Interceptor (Optional)--Use an interceptor to ensure every request has a `requestId` and propagate it to the response header.--```typescript-// common/interceptors/request-id.interceptor.ts-import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';-import { Observable } from 'rxjs';--@Injectable()-export class RequestIdInterceptor implements NestInterceptor {- intercept(context: ExecutionContext, next: CallHandler): Observable<any> {- const request = context.switchToHttp().getRequest();- const response = context.switchToHttp().getResponse();-- const requestId = request.headers['x-request-id'] || `req_${Date.now()}`;- request.requestId = requestId;- response.setHeader('X-Request-ID', requestId);-- return next.handle();- }-}-```+> LoggerService stamps the request ID on every log line on its own (it reads it through `getRequestId()`). Do+> not pass `X-Request-ID` from controller to service, and do not make a provider request-scoped to reach it;+> call `getRequestId()` from `common/services/request-context` when code needs the value.-```typescript-// main.ts-async function bootstrap() {- const app = await NestFactory.create(AppModule);- app.useGlobalInterceptors(new RequestIdInterceptor());- await app.listen(3000);-}-```+### Request ID-> [!NOTE]-> If you use `REQUEST` injection in a service, make sure the provider is **request-scoped** (`@Injectable({ scope: Scope.REQUEST })`) so requestId does not get mixed across requests.+`requestContextMiddleware` (`src/common/middleware/request-context.middleware.ts`, registered in+`src/configure-app.ts`) gives every request an ID. It keeps a client `X-Request-ID` only when it matches+`^[A-Za-z0-9-]{1,128}$` and otherwise generates a UUID, echoes it on the `X-Request-ID` response header,+and runs the request inside AsyncLocalStorage (`runWithRequestId`), so `getRequestId()`, every log line+and every audit row carry it. There is no request-ID interceptor.### Debug WhatsApp Engine@@ -999,8 +965,7 @@ export class EngineTeardownService {### WhatsApp Engine Issues-```markdown-## QR Code Not Generated+#### QR Code Not Generated**Symptom:** Session stuck in 'initializing' status@@ -1017,7 +982,7 @@ export class EngineTeardownService {3. **WhatsApp rate limit**- Wait 5-10 minutes before retrying-## Session Disconnects Randomly+#### Session Disconnects Randomly**Causes & Solutions:**@@ -1032,12 +997,10 @@ export class EngineTeardownService {3. **WhatsApp detected automation**- Add random delays between messages- Avoid sending too many messages quickly-```### Database Issues-````markdown-## Connection Pool Exhausted+#### Connection Pool Exhausted**Symptom:** "too many clients already" error@@ -1055,9 +1018,8 @@ export class EngineTeardownService {},}```-````-## Migration Fails+#### Migration Fails**Symptom:** "relation already exists" error@@ -1074,33 +1036,18 @@ npm run migration:revertnpm run migration:generate --name=FixMigration```-````-### TypeScript/NestJS Issues-```markdown-## Circular Dependency+#### Circular Dependency-**Symptom:** "Cannot read property 'X' of undefined"--**Solution:**-```typescript-// Use forwardRef for circular deps-@Module({- imports: [- forwardRef(() => SessionModule),- ],-})-export class WebhookModule {}+**Symptom:** "Nest can't resolve dependencies" or an undefined injected provider at startup-// In service-constructor(- @Inject(forwardRef(() => SessionService))- private readonly sessionService: SessionService,-) {}-````+**Solution:** this codebase does not use `forwardRef`. Break the cycle by moving the shared piece into+a lower module that both sides import (for example the global `EngineModule`'s `EngineRegistry`), or+by one-directional delegation, as `SessionService` does to `SessionEngineLifecycle` (see the class+comment on `SessionService` in `src/modules/session/session.service.ts`).-## DI Token Not Found+#### DI Token Not Found**Symptom:** "Nest can't resolve dependencies"@@ -1110,17 +1057,15 @@ constructor(- Check if module is imported where needed- Use @Injectable() decorator on services-````-### Docker Issues-```markdown-## Container Keeps Restarting+#### Container Keeps Restarting**Check logs:**+```bashdocker compose logs openwa-api --tail 100-````+```**Common causes:**@@ -1128,7 +1073,7 @@ docker compose logs openwa-api --tail 1002. Database not ready (use depends_on + healthcheck)3. Port already in use-## Chrome Crashes in Docker+#### Chrome Crashes in Docker**Solution:**@@ -1145,8 +1090,6 @@ services:shm_size: '2gb'```-````-## 8.12 Contributing Guide### Getting Started@@ -1161,7 +1104,7 @@ services:7. Commit: `git commit -m 'feat(scope): add amazing feature'`8. Push: `git push origin feat/amazing-feature`9. Open Pull Request-````+```### Code Review Checklistdiff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.tsindex 803422f97..2ec28904c 100644--- a/src/common/docs-governance.spec.ts+++ b/src/common/docs-governance.spec.ts@@ -68,6 +68,13 @@ describe('governance docs match the repository', () => {expect(applied.filter(label => !documented.has(label))).toEqual([]);});+ it('points the circular-dependency advice at the comment that explains the delegation', () => {+ const section = between(read('docs/08-development-guidelines.md'), '#### Circular Dependency', '\n#### ');+ const cited = /`(src\/[^`]+\.ts)`/.exec(section)?.[1];+ expect(cited).toBeDefined();+ expect(read(cited!)).toMatch(/delegates .*one-directionally/);+ });+// The override keeps the service's `build:` section, so `--build` would tag a source build with the// published image name. The README, the release guide and the migration guide give one upgrade command.it('gives the published-image override one upgrade command in the README, docs/14 and docs/15', () => {