Refactor twenty client sdk provisioning for logic function and front-component (#18544)
## 1. The `twenty-client-sdk` Package (Source of Truth)
The monorepo package at `packages/twenty-client-sdk` ships with:
- A **pre-built metadata client** (static, generated from a fixed
schema)
- A **stub core client** that throws at runtime (`CoreApiClient was not
generated...`)
- Both ESM (`.mjs`) and CJS (`.cjs`) bundles in `dist/`
- A `package.json` with proper `exports` map for
`twenty-client-sdk/core`, `twenty-client-sdk/metadata`, and
`twenty-client-sdk/generate`
## 2. Generation & Upload (Server-Side, at Migration Time)
**When**: `WorkspaceMigrationRunnerService.run()` executes after a
metadata schema change.
**What happens in `SdkClientGenerationService.generateAndStore()`**:
1. Copies the stub `twenty-client-sdk` package from the server's assets
(resolved via `SDK_CLIENT_PACKAGE_DIRNAME` — from
`dist/assets/twenty-client-sdk/` in production, or from `node_modules`
in dev)
2. Filters out `node_modules/` and `src/` during copy — only
`package.json` + `dist/` are kept (like an npm publish)
3. Calls `replaceCoreClient()` which uses `@genql/cli` to introspect the
**application-scoped** GraphQL schema and generates a real
`CoreApiClient`, then compiles it to ESM+CJS and overwrites
`dist/core.mjs` and `dist/core.cjs`
4. Archives the **entire package** (with `package.json` + `dist/`) into
`twenty-client-sdk.zip`
5. Uploads the single archive to S3 under
`FileFolder.GeneratedSdkClient`
6. Sets `isSdkLayerStale = true` on the `ApplicationEntity` in the
database
## 3. Invalidation Signal
The `isSdkLayerStale` boolean column on `ApplicationEntity` is the
invalidation mechanism:
- **Set to `true`** by `generateAndStore()` after uploading a new client
archive
- **Checked** by both logic function drivers before execution — if
`true`, they rebuild their local layer
- **Set back to `false`** by `markSdkLayerFresh()` after the driver has
successfully consumed the new archive
Default is `false` so existing applications without a generated client
aren't affected.
## 4a. Logic Functions — Local Driver
**`ensureSdkLayer()`** is called before every execution:
1. Checks if the local SDK layer directory exists AND `isSdkLayerStale`
is `false` → early return
2. Otherwise, cleans the local layer directory
3. Calls `downloadAndExtractToPackage()` which streams the zip from S3
directly to disk and extracts the full package into
`<tmpdir>/sdk/<workspaceId>-<appId>/node_modules/twenty-client-sdk/`
4. Calls `markSdkLayerFresh()` to set `isSdkLayerStale = false`
**At execution time**, `assembleNodeModules()` symlinks everything from
the deps layer's `node_modules/` **except** `twenty-client-sdk`, which
is symlinked from the SDK layer instead. This ensures the logic
function's `import ... from 'twenty-client-sdk/core'` resolves to the
generated client.
## 4b. Logic Functions — Lambda Driver
**`ensureSdkLayer()`** is called during `build()`:
1. Checks if `isSdkLayerStale` is `false` and an existing Lambda layer
ARN exists → early return
2. Otherwise, deletes all existing layer versions for this SDK layer
name
3. Calls `downloadArchiveBuffer()` to get the raw zip from S3 (no disk
extraction)
4. Calls `reprefixZipEntries()` which streams the zip entries into a
**new zip** with the path prefix
`nodejs/node_modules/twenty-client-sdk/` — this is the Lambda layer
convention path. All done in memory, no disk round-trip
5. Publishes the re-prefixed zip as a new Lambda layer via
`publishLayer()`
6. Calls `markSdkLayerFresh()`
**At function creation**, the Lambda is created with **two layers**:
`[depsLayerArn, sdkLayerArn]`. The SDK layer is listed last so it
overwrites the stub `twenty-client-sdk` from the deps layer (later
layers take precedence in Lambda's `/opt` merge).
## 5. Front Components
Front components are built by `app:build` with `twenty-client-sdk/core`
and `twenty-client-sdk/metadata` as **esbuild externals**. The stored
`.mjs` in S3 has unresolved bare import specifiers like `import {
CoreApiClient } from 'twenty-client-sdk/core'`.
SDK import resolution is split between the **frontend host** (fetching &
caching SDK modules) and the **Web Worker** (rewriting imports):
**Server endpoints**:
- `GET /rest/front-components/:id` —
`FrontComponentService.getBuiltComponentStream()` returns the **raw
`.mjs`** directly from file storage. No bundling, no SDK injection.
- `GET /rest/sdk-client/:applicationId/:moduleName` —
`SdkClientController` reads a single file (e.g. `dist/core.mjs`) from
the generated SDK archive via
`SdkClientGenerationService.readFileFromArchive()` and serves it as
JavaScript.
**Frontend host** (`FrontComponentRenderer` in `twenty-front`):
1. Queries `FindOneFrontComponent` which returns `applicationId`,
`builtComponentChecksum`, `usesSdkClient`, and `applicationTokenPair`
2. If `usesSdkClient` is `true`, renders
`FrontComponentRendererWithSdkClient` which calls the
`useApplicationSdkClient` hook
3. `useApplicationSdkClient({ applicationId, accessToken })` checks the
Jotai atom family cache for existing blob URLs. On cache miss, fetches
both SDK modules from `GET /rest/sdk-client/:applicationId/core` and
`/metadata`, creates **blob URLs** for each, and stores them in the atom
family
4. Once the blob URLs are cached, passes them as `sdkClientUrls`
(already blob URLs, not server URLs) to `SharedFrontComponentRenderer` →
`FrontComponentWorkerEffect` → worker's `render()` call via
`HostToWorkerRenderContext`
**Worker** (`remote-worker.ts` in `twenty-sdk`):
1. Fetches the raw component `.mjs` source as text
2. If `sdkClientUrls` are provided and the source contains SDK import
specifiers (`twenty-client-sdk/core`, `twenty-client-sdk/metadata`),
**rewrites** the bare specifiers to the blob URLs received from the host
(e.g. `'twenty-client-sdk/core'` → `'blob:...'`)
3. Creates a blob URL for the rewritten source and `import()`s it
4. Revokes only the component blob URL after the module is loaded — the
SDK blob URLs are owned and managed by the host's Jotai cache
This approach eliminates server-side esbuild bundling on every request,
caches SDK modules per application in the frontend, and keeps the
worker's job to a simple string rewrite.
## Summary Diagram
```
app:build (SDK)
└─ twenty-client-sdk stub (metadata=real, core=stub)
│
▼
WorkspaceMigrationRunnerService.run()
└─ SdkClientGenerationService.generateAndStore()
├─ Copy stub package (package.json + dist/)
├─ replaceCoreClient() → regenerate core.mjs/core.cjs
├─ Zip entire package → upload to S3
└─ Set isSdkLayerStale = true
│
┌────────┴────────────────────┐
▼ ▼
Logic Functions Front Components
│ │
├─ Local Driver ├─ GET /rest/sdk-client/:appId/core
│ └─ downloadAndExtract │ → core.mjs from archive
│ → symlink into │
│ node_modules ├─ Host (useApplicationSdkClient)
│ │ ├─ Fetch SDK modules
└─ Lambda Driver │ ├─ Create blob URLs
└─ downloadArchiveBuffer │ └─ Cache in Jotai atom family
→ reprefixZipEntries │
→ publish as Lambda ├─ GET /rest/front-components/:id
layer │ → raw .mjs (no bundling)
│
└─ Worker (browser)
├─ Fetch component .mjs
├─ Rewrite imports → blob URLs
└─ import() rewritten source
```
## Next PR
- Estimate perf improvement by implementing a redis caching for front
component client storage ( we don't even cache front comp initially )
- Implem frontent blob invalidation sse event from server
---------
Co-authored-by: Charles Bochet <charlesBochet@users.noreply.github.com>
This commit is contained in:
Paul Rastoin
+24
-27
@@ -5,11 +5,9 @@ import {
|
||||
WorkspaceMigrationV2ExceptionCode,
|
||||
} from 'twenty-shared/metadata';
|
||||
import { isDefined } from 'twenty-shared/utils';
|
||||
import { type QueryRunner } from 'typeorm';
|
||||
|
||||
import { FlatApplicationCacheMaps } from 'src/engine/core-modules/application/types/flat-application-cache-maps.type';
|
||||
import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';
|
||||
import { MetadataEventEmitter } from 'src/engine/subscriptions/metadata-event/metadata-event-emitter';
|
||||
import { ALL_MANY_TO_ONE_METADATA_RELATIONS } from 'src/engine/metadata-modules/flat-entity/constant/all-many-to-one-metadata-relations.constant';
|
||||
import { createEmptyFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/constant/create-empty-flat-entity-maps.constant';
|
||||
import {
|
||||
@@ -23,6 +21,7 @@ import { MetadataUniversalFlatEntity } from 'src/engine/metadata-modules/flat-en
|
||||
import { getMetadataFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/utils/get-metadata-flat-entity-maps-key.util';
|
||||
import { getMetadataRelatedMetadataNamesForValidation } from 'src/engine/metadata-modules/flat-entity/utils/get-metadata-related-metadata-names-for-validation.util';
|
||||
import { getSubFlatEntityMapsByApplicationIdsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/get-sub-flat-entity-maps-by-application-ids-or-throw.util';
|
||||
import { MetadataEventEmitter } from 'src/engine/subscriptions/metadata-event/metadata-event-emitter';
|
||||
import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';
|
||||
import { TWENTY_STANDARD_APPLICATION } from 'src/engine/workspace-manager/twenty-standard-application/constants/twenty-standard-applications';
|
||||
import { WorkspaceMigrationV2Exception } from 'src/engine/workspace-manager/workspace-migration.exception';
|
||||
@@ -359,17 +358,14 @@ export class WorkspaceMigrationValidateBuildAndRunService {
|
||||
public async validateBuildAndRunWorkspaceMigrationFromTo(
|
||||
args: WorkspaceMigrationOrchestratorBuildArgs & {
|
||||
idByUniversalIdentifierByMetadataName?: IdByUniversalIdentifierByMetadataName;
|
||||
queryRunner?: QueryRunner;
|
||||
},
|
||||
): Promise<
|
||||
| WorkspaceMigrationOrchestratorFailedResult
|
||||
| WorkspaceMigrationOrchestratorSuccessfulResult
|
||||
| (WorkspaceMigrationOrchestratorSuccessfulResult & {
|
||||
hasSchemaMetadataChanged: boolean;
|
||||
})
|
||||
> {
|
||||
const {
|
||||
idByUniversalIdentifierByMetadataName,
|
||||
queryRunner: externalQueryRunner,
|
||||
...buildArgs
|
||||
} = args;
|
||||
const { idByUniversalIdentifierByMetadataName, ...buildArgs } = args;
|
||||
|
||||
const validateAndBuildResult =
|
||||
await this.workspaceMigrationBuildOrchestratorService
|
||||
@@ -397,24 +393,29 @@ export class WorkspaceMigrationValidateBuildAndRunService {
|
||||
})
|
||||
: validateAndBuildResult.workspaceMigration;
|
||||
|
||||
if (workspaceMigration.actions.length > 0) {
|
||||
const { metadataEvents } = await this.workspaceMigrationRunnerService.run(
|
||||
{
|
||||
workspaceId: args.workspaceId,
|
||||
workspaceMigration,
|
||||
queryRunner: externalQueryRunner,
|
||||
},
|
||||
);
|
||||
|
||||
this.metadataEventEmitter.emitMetadataEvents({
|
||||
metadataEvents,
|
||||
workspaceId: args.workspaceId,
|
||||
});
|
||||
if (workspaceMigration.actions.length === 0) {
|
||||
return {
|
||||
status: 'success',
|
||||
workspaceMigration,
|
||||
hasSchemaMetadataChanged: false,
|
||||
};
|
||||
}
|
||||
|
||||
const { hasSchemaMetadataChanged, metadataEvents } =
|
||||
await this.workspaceMigrationRunnerService.run({
|
||||
workspaceId: args.workspaceId,
|
||||
workspaceMigration,
|
||||
});
|
||||
|
||||
this.metadataEventEmitter.emitMetadataEvents({
|
||||
metadataEvents: metadataEvents,
|
||||
workspaceId: args.workspaceId,
|
||||
});
|
||||
|
||||
return {
|
||||
status: 'success',
|
||||
workspaceMigration,
|
||||
hasSchemaMetadataChanged,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -423,10 +424,7 @@ export class WorkspaceMigrationValidateBuildAndRunService {
|
||||
workspaceId,
|
||||
isSystemBuild = false,
|
||||
applicationUniversalIdentifier,
|
||||
queryRunner,
|
||||
}: ValidateBuildAndRunWorkspaceMigrationFromMatriceArgs & {
|
||||
queryRunner?: QueryRunner;
|
||||
}): Promise<
|
||||
}: ValidateBuildAndRunWorkspaceMigrationFromMatriceArgs): Promise<
|
||||
| WorkspaceMigrationOrchestratorFailedResult
|
||||
| WorkspaceMigrationOrchestratorSuccessfulResult
|
||||
> {
|
||||
@@ -453,7 +451,6 @@ export class WorkspaceMigrationValidateBuildAndRunService {
|
||||
dependencyAllFlatEntityMaps,
|
||||
additionalCacheDataMaps,
|
||||
idByUniversalIdentifierByMetadataName,
|
||||
queryRunner,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
+22
-25
@@ -3,7 +3,7 @@ import { InjectDataSource } from '@nestjs/typeorm';
|
||||
|
||||
import { type AllMetadataName } from 'twenty-shared/metadata';
|
||||
import { isDefined } from 'twenty-shared/utils';
|
||||
import { DataSource, type QueryRunner } from 'typeorm';
|
||||
import { DataSource } from 'typeorm';
|
||||
|
||||
import { LoggerService } from 'src/engine/core-modules/logger/logger.service';
|
||||
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
|
||||
@@ -154,21 +154,18 @@ export class WorkspaceMigrationRunnerService {
|
||||
run = async ({
|
||||
workspaceMigration: { actions, applicationUniversalIdentifier },
|
||||
workspaceId,
|
||||
queryRunner: externalQueryRunner,
|
||||
}: {
|
||||
workspaceMigration: WorkspaceMigration;
|
||||
workspaceId: string;
|
||||
queryRunner?: QueryRunner;
|
||||
}): Promise<{
|
||||
allFlatEntityMaps: AllFlatEntityMaps;
|
||||
metadataEvents: MetadataEvent[];
|
||||
hasSchemaMetadataChanged: boolean;
|
||||
}> => {
|
||||
this.logger.time('Runner', 'Total execution');
|
||||
this.logger.time('Runner', 'Initial cache retrieval');
|
||||
|
||||
const queryRunner =
|
||||
externalQueryRunner ?? this.coreDataSource.createQueryRunner();
|
||||
const isTransactionAlreadyActive = queryRunner.isTransactionActive;
|
||||
const queryRunner = this.coreDataSource.createQueryRunner();
|
||||
|
||||
const actionMetadataNames = [
|
||||
...new Set(actions.flatMap((action) => action.metadataName)),
|
||||
@@ -219,10 +216,8 @@ export class WorkspaceMigrationRunnerService {
|
||||
|
||||
this.logger.time('Runner', 'Transaction execution');
|
||||
|
||||
if (!isTransactionAlreadyActive) {
|
||||
await queryRunner.connect();
|
||||
await queryRunner.startTransaction();
|
||||
}
|
||||
await queryRunner.connect();
|
||||
await queryRunner.startTransaction();
|
||||
|
||||
try {
|
||||
const allMetadataEvents: MetadataEvent[] = [];
|
||||
@@ -250,9 +245,7 @@ export class WorkspaceMigrationRunnerService {
|
||||
allMetadataEvents.push(...metadataEvents);
|
||||
}
|
||||
|
||||
if (!isTransactionAlreadyActive) {
|
||||
await queryRunner.commitTransaction();
|
||||
}
|
||||
await queryRunner.commitTransaction();
|
||||
|
||||
this.logger.timeEnd('Runner', 'Transaction execution');
|
||||
|
||||
@@ -261,18 +254,24 @@ export class WorkspaceMigrationRunnerService {
|
||||
workspaceId,
|
||||
});
|
||||
|
||||
const hasSchemaMetadataChanged =
|
||||
allFlatEntityMapsKeys.includes('flatObjectMetadataMaps') ||
|
||||
allFlatEntityMapsKeys.includes('flatFieldMetadataMaps');
|
||||
|
||||
this.logger.timeEnd('Runner', 'Total execution');
|
||||
|
||||
return { allFlatEntityMaps, metadataEvents: allMetadataEvents };
|
||||
return {
|
||||
allFlatEntityMaps,
|
||||
metadataEvents: allMetadataEvents,
|
||||
hasSchemaMetadataChanged,
|
||||
};
|
||||
} catch (error) {
|
||||
if (!isTransactionAlreadyActive && queryRunner.isTransactionActive) {
|
||||
await queryRunner.rollbackTransaction().catch((rollbackError) =>
|
||||
// oxlint-disable-next-line no-console
|
||||
console.trace(
|
||||
`Failed to rollback transaction: ${rollbackError.message}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
await queryRunner.rollbackTransaction().catch((rollbackError) =>
|
||||
// oxlint-disable-next-line no-console
|
||||
console.trace(
|
||||
`Failed to rollback transaction: ${rollbackError.message}`,
|
||||
),
|
||||
);
|
||||
|
||||
const invertedActions = [...actions].reverse();
|
||||
|
||||
@@ -299,9 +298,7 @@ export class WorkspaceMigrationRunnerService {
|
||||
code: WorkspaceMigrationRunnerExceptionCode.INTERNAL_SERVER_ERROR,
|
||||
});
|
||||
} finally {
|
||||
if (!isTransactionAlreadyActive) {
|
||||
await queryRunner.release();
|
||||
}
|
||||
await queryRunner.release();
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user