Merge origin/beta into feature/cdc-connector

Resolves conflicts for PR #510 (base: beta):
- package.json: keep protospack ^3.40.0-beta.20 (carries CDC→Iceberg fields);
  package-lock.json reconciled (protospack was the only dep delta vs beta).
- connection-test controller/service/dto: keep BOTH feature sets — our CDC
  prerequisites validation AND beta's refresh-catalog endpoints.
- Adopt beta's cache-first catalog reads (connections-api proxy) over our gRPC
  path. connectionTestListTables now enriches each table with primary_keys
  derived from the cached columns endpoint (is_primary_key), preserving the
  CDC create flow's need for PKs under the new architecture; spec updated.
- docsfera.json resolved to ours; regenerated on next app bootstrap.

connection-test spec: 6 passed. tsc --noEmit: clean.

Co-Authored-By: WOZCODE <contact@withwoz.com>

src/modules/connection-test/connection-test.controller.ts

@@ -24,6 +24,9 @@ import {
   GetTableMetadataReq,
   ValidateCdcPrerequisitesReq,
   ValidateCdcPrerequisitesRes,
+  RefreshCatalogReq,
+  RefreshCatalogRes,
+  RefreshCatalogStatusReq,
 } from './dto/connection-test';
 import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import { Authenticated, RequireModule } from 'src/decorators/authentication.decorator';
@@ -90,7 +93,7 @@ export class ConnectionTestController {
     });
     return this.connectionTestService.connectionTestListSchemas(
       body,
-      user.customer_name,
+      user,
     );
   }
 
@@ -107,7 +110,7 @@ export class ConnectionTestController {
     });
     return this.connectionTestService.connectionTestListTables(
       body,
-      user.customer_name,
+      user,
     );
   }
 
@@ -124,7 +127,7 @@ export class ConnectionTestController {
     });
     return this.connectionTestService.getTableMetadata(
       body,
-      user.customer_name,
+      user,
     );
   }
 
@@ -144,4 +147,35 @@ export class ConnectionTestController {
       user.customer_name,
     );
   }
+
+  @Post('refresh-catalog')
+  @ApiOkResponse({ type: RefreshCatalogRes })
+  @HttpCode(HttpStatus.ACCEPTED)
+  async refreshCatalog(
+    @User() user: RequestUser,
+    @Body(new ValidationPipe()) body: RefreshCatalogReq,
+  ) {
+    this.logger.info('/connection-test/refresh-catalog', {
+      user: user.user_id,
+      customer: user.customer_name,
+      connection: body.connection_id,
+    });
+    return this.connectionTestService.refreshCatalog(body, user);
+  }
+
+  @Post('refresh-catalog/status')
+  @ApiOkResponse({ type: RefreshCatalogRes })
+  @HttpCode(HttpStatus.OK)
+  async refreshCatalogStatus(
+    @User() user: RequestUser,
+    @Body(new ValidationPipe()) body: RefreshCatalogStatusReq,
+  ) {
+    this.logger.info('/connection-test/refresh-catalog/status', {
+      user: user.user_id,
+      customer: user.customer_name,
+      connection: body.connection_id,
+      session: body.session_id,
+    });
+    return this.connectionTestService.refreshCatalogStatus(body, user);
+  }
 }

src/modules/connection-test/connection-test.module.ts

@@ -5,10 +5,17 @@ import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import { ClientsModule } from '@nestjs/microservices';
 import { ConnectionTestClientConfiguration } from './connection-test-client.config';
 import { ConnectionModule } from '../connection/connection.module';
+import { ConnectionsApiModule } from '../connections-api/connections-api.module';
+import { PlatformApiModule } from '../platform-api/platform-api.module';
 const client = new ConnectionTestClientConfiguration();
 @Module({
   controllers: [ConnectionTestController],
   providers: [ConnectionTestService, DadosferaLogger],
-  imports: [ClientsModule.register([client.providerOptions]), ConnectionModule],
+  imports: [
+    ClientsModule.register([client.providerOptions]),
+    ConnectionModule,
+    ConnectionsApiModule,
+    PlatformApiModule,
+  ],
 })
 export class ConnectionTestModule {}

src/modules/connection-test/connection-test.service.spec.ts

@@ -0,0 +1,223 @@
+import { ConnectionTestService } from './connection-test.service';
+import { RequestUser } from 'src/decorators/user.decorator';
+
+describe('ConnectionTestService catalog cache', () => {
+  const user: RequestUser = {
+    user_id: 'user-id',
+    username: 'user@example.com',
+    permissions: [],
+    customer_id: 'customer-id',
+    customer_name: 'customer-name',
+    customer_tier: 'standard',
+    access_token: 'token',
+    customer_modules: [],
+    roles: [],
+  };
+  const grpcClient = { getService: jest.fn().mockReturnValue({}) };
+  const connectionsService = {};
+  const connectionsApiService = { proxy: jest.fn() };
+  const platformApiService = { proxy: jest.fn() };
+  let service: ConnectionTestService;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    service = new ConnectionTestService(
+      grpcClient as any,
+      connectionsService as any,
+      connectionsApiService as any,
+      platformApiService as any,
+    );
+  });
+
+  it('keeps the existing schemas response contract', async () => {
+    connectionsApiService.proxy.mockResolvedValue({
+      schemas: [{ schema_name: 'analytics' }, { schema_name: 'public' }],
+    });
+
+    await expect(
+      service.connectionTestListSchemas(
+        { connection_id: 'config-id', plugin: 'postgresql' },
+        user,
+      ),
+    ).resolves.toEqual({
+      operation_result: true,
+      schema_list: ['analytics', 'public'],
+    });
+  });
+
+  it('lists tables and enriches each with its cached primary keys', async () => {
+    connectionsApiService.proxy
+      // list-tables call (names only from the catalog cache)
+      .mockResolvedValueOnce({
+        tables: [{ table_name: 'customers' }, { table_name: 'orders' }],
+      })
+      // per-table columns calls: customers has a PK, orders has none
+      .mockResolvedValueOnce({
+        columns: [
+          { column_name: 'id', data_type: 'bigint', is_primary_key: true },
+          { column_name: 'name', data_type: 'text', is_primary_key: false },
+        ],
+      })
+      .mockResolvedValueOnce({
+        columns: [
+          { column_name: 'total', data_type: 'numeric', is_primary_key: false },
+        ],
+      });
+
+    await expect(
+      service.connectionTestListTables(
+        {
+          connection_id: 'config-id',
+          plugin: 'postgresql',
+          schema: 'public',
+        },
+        user,
+      ),
+    ).resolves.toEqual({
+      operation_result: true,
+      table_list: ['customers', 'orders'],
+      tables: [
+        { table_name: 'customers', primary_keys: ['id'] },
+        { table_name: 'orders', primary_keys: [] },
+      ],
+    });
+  });
+
+  it('maps cached columns to the existing table metadata contract', async () => {
+    connectionsApiService.proxy.mockResolvedValue({
+      columns: [
+        {
+          column_name: 'id',
+          data_type: 'bigint',
+          is_primary_key: true,
+        },
+      ],
+    });
+
+    await expect(
+      service.getTableMetadata(
+        {
+          connection_id: 'config-id',
+          plugin: 'postgresql',
+          schema: 'public',
+          table_list: ['customers'],
+        },
+        user,
+      ),
+    ).resolves.toEqual({
+      operation_result: true,
+      tables_metadata: [
+        {
+          table_name: 'customers',
+          columns: [
+            {
+              name: 'id',
+              type: 'bigint',
+              is_primary_key: true,
+            },
+          ],
+          references: [],
+        },
+      ],
+    });
+    expect(connectionsApiService.proxy).toHaveBeenCalledWith(
+      'GET',
+      '/connection_catalog/config-id/schemas/public/tables/customers/columns',
+      user,
+    );
+  });
+
+  it('submits a catalog refresh without holding the request open', async () => {
+    platformApiService.proxy.mockResolvedValue({
+      session_id: 'session-id',
+      date: '20260731',
+    });
+
+    await expect(
+      service.refreshCatalog(
+        { connection_id: 'config-id', plugin: 'postgresql' },
+        user,
+      ),
+    ).resolves.toEqual({
+      operation_result: true,
+      status: 'PENDING',
+      session_id: 'session-id',
+      date: '20260731',
+    });
+
+    expect(platformApiService.proxy).toHaveBeenCalledWith(
+      'POST',
+      '/connection_test',
+      user,
+      {
+        customer_id: user.customer_name,
+        plugin: 'postgresql',
+        task: {
+          task_type: 'refresh_catalog',
+          connection: {
+            provider: 'connection_manager',
+            config_id: 'config-id',
+          },
+        },
+      },
+    );
+  });
+
+  it('keeps polling without changing the catalog pointer while pending', async () => {
+    platformApiService.proxy.mockResolvedValue({ status: 'PENDING' });
+
+    await expect(
+      service.refreshCatalogStatus(
+        {
+          connection_id: 'config-id',
+          plugin: 'postgresql',
+          session_id: 'session-id',
+          date: '20260731',
+        },
+        user,
+      ),
+    ).resolves.toEqual({
+      operation_result: false,
+      status: 'PENDING',
+      session_id: 'session-id',
+      date: '20260731',
+    });
+
+    expect(connectionsApiService.proxy).not.toHaveBeenCalled();
+  });
+
+  it('publishes the catalog pointer after the refresh finishes', async () => {
+    platformApiService.proxy.mockResolvedValue({ status: 'DONE' });
+    connectionsApiService.proxy.mockResolvedValue({
+      last_catalog_refresh_status: 'SUCCESS',
+    });
+
+    await expect(
+      service.refreshCatalogStatus(
+        {
+          connection_id: 'config/id',
+          plugin: 'postgresql',
+          session_id: 'session-id',
+          date: '20260731',
+        },
+        user,
+      ),
+    ).resolves.toEqual({
+      operation_result: true,
+      status: 'DONE',
+      session_id: 'session-id',
+      date: '20260731',
+    });
+
+    expect(connectionsApiService.proxy).toHaveBeenCalledWith(
+      'PUT',
+      '/connection_config/config%2Fid/catalog_metadata',
+      user,
+      {
+        last_catalog_refresh_status: 'SUCCESS',
+        last_catalog_connection_test_date: '20260731',
+        last_catalog_connection_test_session_id: 'session-id',
+      },
+    );
+  });
+});

src/modules/connection-test/connection-test.service.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { HttpException, HttpStatus, Inject, Injectable } from '@nestjs/common';
 import { ClientGrpc } from '@nestjs/microservices';
 import { ConnectionTest } from '@dadosfera/protospack-v2';
 import { lastValueFrom } from 'rxjs';
@@ -15,6 +15,9 @@ import {
   GetTableMetadataRes,
   ValidateCdcPrerequisitesReq,
   ValidateCdcPrerequisitesRes,
+  RefreshCatalogReq,
+  RefreshCatalogRes,
+  RefreshCatalogStatusReq,
 } from './dto/connection-test';
 import { ConnectionClientService } from '../connection/client.service';
 import {
@@ -23,6 +26,8 @@ import {
 } from '../connection/dtos/connection';
 import { RequestUser } from 'src/decorators/user.decorator';
 import { PackTheMetadata } from 'src/utils/PackTheMetadata';
+import { ConnectionsApiService } from '../connections-api/connections-api.service';
+import { PlatformApiService } from '../platform-api/platform-api.service';
 
 @Injectable()
 export class ConnectionTestService {
@@ -30,6 +35,8 @@ export class ConnectionTestService {
   constructor(
     @Inject('ConnectionTestGrpcClient') private readonly grpcClient: ClientGrpc,
     private connectionsService: ConnectionClientService,
+    private connectionsApiService: ConnectionsApiService,
+    private platformApiService: PlatformApiService,
   ) {
     this.connectionTestReadClient =
       grpcClient.getService<ConnectionTest.ReadService.ConnectionTestReadServices>(
@@ -149,46 +156,162 @@ export class ConnectionTestService {
   }
   async connectionTestListSchemas(
     body: ConnectionTestListSchemasReq,
-    customer_name: string,
+    user: RequestUser,
   ): Promise<ConnectionTestListSchemasRes> {
-    const { connection_id, plugin } = body;
-    return lastValueFrom(
-      this.connectionTestReadClient.ListSchemas({
-        connection_id,
-        customer_name,
-        plugin,
-      }),
+    const result = await this.connectionsApiService.proxy(
+      'GET',
+      `/connection_catalog/${encodeURIComponent(body.connection_id)}/schemas`,
+      user,
     );
+    return {
+      operation_result: true,
+      schema_list: result.schemas.map((schema) => schema.schema_name),
+    };
   }
+
   async connectionTestListTables(
     body: ConnectionTestListTablesReq,
-    customer_name: string,
+    user: RequestUser,
   ): Promise<ConnectionTestListTablesRes> {
-    const { connection_id, plugin, schema } = body;
-    return lastValueFrom(
-      this.connectionTestReadClient.ListTables({
-        connection_id,
-        customer_name,
-        plugin,
-        schema,
+    const result = await this.connectionsApiService.proxy(
+      'GET',
+      `/connection_catalog/${encodeURIComponent(body.connection_id)}` +
+        `/schemas/${encodeURIComponent(body.schema)}/tables`,
+      user,
+    );
+    const table_names: string[] = result.tables.map((table) => table.table_name);
+    // CDC create needs the primary keys per table (used to build the deduped
+    // Iceberg identifier-fields). The catalog-cache list-tables endpoint returns
+    // only names, so fetch each table's columns from the cache and keep the ones
+    // flagged is_primary_key. Reads hit the stored catalog snapshot (populated by
+    // refresh-catalog), never the live connection.
+    const tables = await Promise.all(
+      table_names.map(async (table_name) => {
+        const columns = await this.connectionsApiService.proxy(
+          'GET',
+          `/connection_catalog/${encodeURIComponent(body.connection_id)}` +
+            `/schemas/${encodeURIComponent(body.schema)}` +
+            `/tables/${encodeURIComponent(table_name)}/columns`,
+          user,
+        );
+        return {
+          table_name,
+          primary_keys: columns.columns
+            .filter((column) => column.is_primary_key)
+            .map((column) => column.column_name),
+        };
       }),
     );
+    return {
+      operation_result: true,
+      table_list: table_names,
+      tables,
+    };
   }
 
   async getTableMetadata(
     body: GetTableMetadataReq,
-    customer_name: string,
+    user: RequestUser,
   ): Promise<GetTableMetadataRes> {
-    const { schema, plugin, table_list, connection_id } = body;
-    return lastValueFrom(
-      this.connectionTestReadClient.GetTableMetadata({
-        connection_id,
-        customer_name,
-        plugin,
-        schema,
-        table_list,
+    const tables_metadata = await Promise.all(
+      body.table_list.map(async (table_name) => {
+        const result = await this.connectionsApiService.proxy(
+          'GET',
+          `/connection_catalog/${encodeURIComponent(body.connection_id)}` +
+            `/schemas/${encodeURIComponent(body.schema)}` +
+            `/tables/${encodeURIComponent(table_name)}/columns`,
+          user,
+        );
+        return {
+          table_name,
+          columns: result.columns.map((column) => ({
+            name: column.column_name,
+            type: column.data_type,
+            is_primary_key: column.is_primary_key,
+          })),
+          references: [],
+        };
       }),
     );
+    return { operation_result: true, tables_metadata };
+  }
+
+  async refreshCatalog(
+    body: RefreshCatalogReq,
+    user: RequestUser,
+  ): Promise<RefreshCatalogRes> {
+    const task = await this.platformApiService.proxy(
+      'POST',
+      '/connection_test',
+      user,
+      {
+        customer_id: user.customer_name,
+        plugin: body.plugin,
+        task: {
+          task_type: 'refresh_catalog',
+          connection: {
+            provider: 'connection_manager',
+            config_id: body.connection_id,
+          },
+        },
+      },
+    );
+
+    if (!task.session_id || !task.date) {
+      throw new HttpException(
+        'Platform API did not return a catalog refresh task identifier',
+        HttpStatus.BAD_GATEWAY,
+      );
+    }
+
+    return {
+      operation_result: true,
+      status: 'PENDING',
+      session_id: task.session_id,
+      date: task.date,
+    };
+  }
+
+  async refreshCatalogStatus(
+    body: RefreshCatalogStatusReq,
+    user: RequestUser,
+  ): Promise<RefreshCatalogRes> {
+    const result = await this.platformApiService.proxy(
+      'POST',
+      '/connection_test/status',
+      user,
+      {
+        session_id: body.session_id,
+        date: body.date,
+      },
+    );
+
+    if (result.status === 'DONE') {
+      await this.connectionsApiService.proxy(
+        'PUT',
+        `/connection_config/${encodeURIComponent(
+          body.connection_id,
+        )}/catalog_metadata`,
+        user,
+        {
+          last_catalog_refresh_status: 'SUCCESS',
+          last_catalog_connection_test_date: body.date,
+          last_catalog_connection_test_session_id: body.session_id,
+        },
+      );
+    } else if (result.status === 'ERROR' || result.status === 'EXPIRED') {
+      throw new HttpException(
+        `Catalog refresh finished with status ${result.status}`,
+        HttpStatus.BAD_GATEWAY,
+      );
+    }
+
+    return {
+      operation_result: result.status === 'DONE',
+      status: result.status,
+      session_id: body.session_id,
+      date: body.date,
+    };
   }
 
   async validateCdcPrerequisites(

src/modules/connection-test/dto/connection-test.ts

@@ -1,5 +1,5 @@
 import { ApiProperty, ApiPropertyOptional, OmitType } from '@nestjs/swagger';
-import { IsString, IsOptional } from 'class-validator';
+import { IsIn, IsString, IsOptional } from 'class-validator';
 import { DatabaseConnectionPropertiesDto } from 'src/modules/connection/dtos/connection';
 import { CreateConnectionDto } from 'src/modules/connection/dtos/connection';
 export class ColumnDto {
@@ -7,6 +7,8 @@ export class ColumnDto {
   name: string;
   @ApiProperty()
   type: string;
+  @ApiProperty()
+  is_primary_key: boolean;
 }
 export class TableMetadataDto {
   @ApiProperty()
@@ -168,3 +170,37 @@ export class ValidateCdcPrerequisitesRes {
   @ApiProperty({ type: [CdcCheckDto] })
   checks: CdcCheckDto[];
 }
+
+export class RefreshCatalogReq {
+  @ApiProperty()
+  @IsString()
+  connection_id: string;
+
+  @ApiProperty({ enum: ['oracle', 'mysql', 'postgresql', 'sqlserver'] })
+  @IsIn(['oracle', 'mysql', 'postgresql', 'sqlserver'])
+  plugin: string;
+}
+
+export class RefreshCatalogStatusReq extends RefreshCatalogReq {
+  @ApiProperty()
+  @IsString()
+  session_id: string;
+
+  @ApiProperty()
+  @IsString()
+  date: string;
+}
+
+export class RefreshCatalogRes {
+  @ApiProperty()
+  operation_result: boolean;
+
+  @ApiProperty()
+  status: string;
+
+  @ApiProperty()
+  session_id: string;
+
+  @ApiProperty()
+  date: string;
+}