@lenne.tech/nest-server 12.1.1 → 12.2.0

package/src/core/modules/sync/interfaces/core-sync.interfaces.ts

@@ -0,0 +1,85 @@
+/**
+ * The wire format of the sync protocol (`docs/offline-sync-protocol.md`) and the hook of the `custom` strategy.
+ * Types only.
+ */
+
+/** A pushed change (protocol §6.2) */
+export interface ISyncPushItem {
+  /** The version the change is based on; absent only on the item that creates the record */
+  baseVersion?: number;
+  /** The fields to set (`upsert`); validated against the model's input like any create/update */
+  data?: Record<string, unknown>;
+  /** For `merge`: the field names the client changed. Without it, every key in `data` counts as changed */
+  fields?: string[];
+  /** The record's id, in the model's format */
+  id: string;
+  /** Unique per change, generated by the client; the same change sent again carries the same id */
+  mutationId: string;
+  op: SyncPushOp;
+}
+
+export type SyncPushOp = 'delete' | 'upsert';
+
+/** Protocol §7 */
+export type SyncItemStatus = 'applied' | 'conflict' | 'merged' | 'not_found' | 'rejected' | 'retry';
+
+/** Protocol §7 — the reason of a `rejected` item */
+export type SyncRejectCode = 'CUSTOM_REFUSED' | 'FORBIDDEN' | 'ID_UNAVAILABLE' | 'INVALID_ID' | 'VALIDATION_FAILED';
+
+/**
+ * A record as a pull delivers it (protocol §5.2): a live record carries its content in `data`, a tombstone carries
+ * no `data` — only its id, version, times, `tenantId` and the model's scope fields (protocol §2).
+ */
+export interface ISyncRecord {
+  [scopeField: string]: unknown;
+  data?: Record<string, unknown>;
+  deletedAt: Date | null;
+  id: string;
+  updatedAt?: Date;
+  version: number;
+}
+
+/** Protocol §6.6 */
+export interface ISyncPushResult {
+  code?: SyncRejectCode;
+  details?: unknown;
+  id: string;
+  mutationId: string;
+  /** The server's record (`conflict`, `merged`) */
+  record?: ISyncRecord;
+  status: SyncItemStatus;
+  version?: number;
+}
+
+/** Protocol §5.2 */
+export interface ISyncPullResult {
+  cursor: string;
+  hasMore: boolean;
+  items: ISyncRecord[];
+}
+
+/** Protocol §8 */
+export type SyncResyncReason = 'access' | 'horizon' | 'invalid';
+
+/** What `resolveSyncConflict()` receives under the `custom` strategy */
+export interface ISyncConflictContext {
+  /** What the client sent */
+  change: { baseVersion?: number; data?: Record<string, unknown>; fields?: string[]; op: SyncPushOp };
+  /** The authenticated caller, as the controller received it */
+  currentUser: any;
+  id: string;
+  model: string;
+  /** The record as the caller may see it now, a live record (a tombstone always conflicts) */
+  server: ISyncRecord;
+}
+
+/**
+ * The answer of `resolveSyncConflict()`: the fields to write on top of the server's record, a deletion, or a refusal
+ * (`rejected` / `CUSTOM_REFUSED`). The write runs through the same pipeline as every push.
+ */
+export type SyncConflictResolution = { data: Record<string, unknown> } | { delete: true } | { refuse: true };
+
+/** A model service whose model declares `strategy: 'custom'` implements this */
+export interface SyncConflictResolver {
+  resolveSyncConflict(context: ISyncConflictContext): Promise<SyncConflictResolution> | SyncConflictResolution;
+}

package/src/core/modules/sync/models/core-sync-hint.model.ts

@@ -0,0 +1,18 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator.js';
+import { RoleEnum } from '../../../common/enums/role.enum.js';
+
+/**
+ * A change hint of offline sync (protocol §9): the model changed at this time — nothing else, no record, no id, no
+ * tenant. A client answers it with a pull. Who receives it was decided before it was sent.
+ */
+@ObjectType('SyncHint', { description: 'A synchronized model changed: pull it' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class CoreSyncHintModel {
+  @Field(() => Date, { description: 'When the change was sent' })
+  at: Date;
+
+  @Field(() => String, { description: 'The changed model, as in GET /sync/{model}' })
+  model: string;
+}

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -26,6 +26,7 @@ import {
 import { DataSourceConfigError } from '../../common/persistence/data-source.config.js';
 import type { DataStore } from '../../common/persistence/data-store.interface.js';
 import { getStoreToken } from '../../common/persistence/persistence.tokens.js';
+import { getSyncAccessListener } from '../../common/persistence/sync-access.registry.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { ResolvedTenantContext, setTenantContextResolver } from '../../common/services/core-tenant-context.registry.js';
 import { CoreRedisService } from '../../common/services/core-redis.service.js';
@@ -383,6 +384,13 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
   invalidateTenant(tenantId: string): void {
     this.clearTenant(tenantId);
     this.publishInvalidation({ scope: 'tenant', tenantId });
+    // Offline sync: the tenant's members resync on their next pull (a no-op without the sync module). Once, here —
+    // the epoch lives in the database, so a replica receiving the broadcast must not bump it again
+    void getSyncAccessListener()
+      ?.tenantInvalidated(tenantId)
+      .catch((error) =>
+        this.logger.warn(`Sync access epoch of tenant ${tenantId} not bumped: ${(error as Error)?.message ?? error}`),
+      );
   }
 
   /**

package/src/core.module.ts

@@ -84,6 +84,7 @@ import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config
 import { CorePermissionsModule } from './core/modules/permissions/core-permissions.module.js';
 import { CoreSystemSetupModule } from './core/modules/system-setup/core-system-setup.module.js';
 import { CoreApiTokenModule } from './core/modules/api-token/core-api-token.module.js';
+import { CoreSyncModule } from './core/modules/sync/core-sync.module.js';
 import { CoreTenantModule } from './core/modules/tenant/core-tenant.module.js';
 
 /** Configuration warnings of `forRoot()`, through Nest's logger so log levels and a project's logger apply. */
@@ -676,6 +677,30 @@ export class CoreModule implements NestModule {
       imports.push(CoreApiTokenModule.forRoot({ ...overrides?.apiToken }));
     }
 
+    // Add CoreSyncModule when sync is configured (boolean shorthand, presence implies enabled). Without it nothing of
+    // offline sync is registered: no route, no infrastructure model, no listener on the write paths.
+    const syncConfig = config.sync;
+    if (
+      syncConfig === true ||
+      (typeof syncConfig === 'object' && syncConfig !== null && syncConfig.enabled !== false)
+    ) {
+      imports.push(
+        CoreSyncModule.forRoot({
+          ...overrides?.sync,
+          // The subscription needs GraphQL, and is switched off with its channel or with all hints
+          graphQlHints:
+            config.graphQl !== false &&
+            !(
+              typeof syncConfig === 'object' &&
+              (syncConfig.hints === false ||
+                (typeof syncConfig.hints === 'object' &&
+                  (syncConfig.hints.graphql === false || syncConfig.hints.enabled === false)))
+            ),
+          path: typeof syncConfig === 'object' ? syncConfig.path : undefined,
+        }),
+      );
+    }
+
     // Set exports
     const exports: any[] = [
       ConfigService,

package/src/index.ts

@@ -98,6 +98,8 @@ export * from './core/common/persistence/mongoose-data-store.js';
 export * from './core/common/persistence/persisted-model.decorator.js';
 export * from './core/common/persistence/persistence.tokens.js';
 export * from './core/common/persistence/persistence-runtime.registry.js';
+export { VersionConflictError } from './core/common/persistence/policies/sync.policy.js';
+export * from './core/common/persistence/sync-model.js';
 export * from './core/common/persistence/unsupported-capability.error.js';
 export * from './core/common/persistence/sql/mysql/mysql-data-store.js';
 export * from './core/common/persistence/sql/mysql/mysql-lock-store.js';
@@ -276,6 +278,25 @@ export * from './core/modules/system-setup/core-system-setup.controller.js';
 export * from './core/modules/system-setup/core-system-setup.module.js';
 export * from './core/modules/system-setup/core-system-setup.service.js';
 
+// =====================================================================================================================
+// Core - Modules - Sync (offline sync)
+// =====================================================================================================================
+
+export * from './core/modules/sync/core-sync-base.controller.js';
+export * from './core/modules/sync/core-sync.constants.js';
+export * from './core/modules/sync/core-sync.controller.js';
+export * from './core/modules/sync/core-sync.decorators.js';
+export * from './core/modules/sync/core-sync-hints.controller.js';
+export * from './core/modules/sync/core-sync-hints.service.js';
+export * from './core/modules/sync/core-sync-infrastructure.models.js';
+export * from './core/modules/sync/core-sync.module.js';
+export * from './core/modules/sync/core-sync-mutation.store.js';
+export * from './core/modules/sync/core-sync.resolver.js';
+export * from './core/modules/sync/core-sync.service.js';
+export * from './core/modules/sync/core-sync-state.store.js';
+export * from './core/modules/sync/interfaces/core-sync.interfaces.js';
+export * from './core/modules/sync/models/core-sync-hint.model.js';
+
 // =====================================================================================================================
 // Core - Modules - Tus
 // =====================================================================================================================

package/src/server/modules/sync-note/inputs/sync-note-create.input.ts

@@ -0,0 +1,14 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../../core/common/decorators/restricted.decorator.js';
+import { UnifiedField } from '../../../../core/common/decorators/unified-field.decorator.js';
+import { RoleEnum } from '../../../../core/common/enums/role.enum.js';
+import { SyncNoteInput } from './sync-note.input.js';
+
+/** Input of a pushed note that creates it; the client chose its id (protocol §3) */
+@InputType({ description: 'Input to create a synchronized note' })
+@Restricted(RoleEnum.ADMIN)
+export class SyncNoteCreateInput extends SyncNoteInput {
+  @UnifiedField({ description: 'Title of the note', roles: RoleEnum.S_EVERYONE })
+  override title: string = undefined;
+}

package/src/server/modules/sync-note/inputs/sync-note.input.ts

@@ -0,0 +1,23 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../../core/common/decorators/restricted.decorator.js';
+import { UnifiedField } from '../../../../core/common/decorators/unified-field.decorator.js';
+import { RoleEnum } from '../../../../core/common/enums/role.enum.js';
+import { CoreInput } from '../../../../core/common/inputs/core-input.input.js';
+
+/**
+ * Input of a pushed change of a note — validated and whitelisted like a request body, so a client can set only what
+ * is declared here (never `createdBy`, `version` or `deletedAt`)
+ */
+@InputType({ description: 'Input to change a synchronized note' })
+@Restricted(RoleEnum.ADMIN)
+export class SyncNoteInput extends CoreInput {
+  @UnifiedField({ description: 'Text of the note', isOptional: true, roles: RoleEnum.S_EVERYONE })
+  body?: string = undefined;
+
+  @UnifiedField({ description: 'Priority of the note', isOptional: true, roles: RoleEnum.S_EVERYONE })
+  priority?: number = undefined;
+
+  @UnifiedField({ description: 'Title of the note', isOptional: true, roles: RoleEnum.S_EVERYONE })
+  title?: string = undefined;
+}

package/src/server/modules/sync-note/sync-note.model.ts

@@ -0,0 +1,77 @@
+import { ObjectType } from '@nestjs/graphql';
+import type { Types } from 'mongoose';
+
+import { Restricted } from '../../../core/common/decorators/restricted.decorator.js';
+import { UnifiedField } from '../../../core/common/decorators/unified-field.decorator.js';
+import { RoleEnum } from '../../../core/common/enums/role.enum.js';
+import { equalIds } from '../../../core/common/helpers/id.helper.js';
+import { CorePersistenceModel } from '../../../core/common/models/core-persistence.model.js';
+import {
+  objectIdType,
+  Schema as MongooseSchema,
+  SchemaFactory,
+} from '../../../core/common/persistence/mongo/mongoose-compat.js';
+import { PersistedModel } from '../../../core/common/persistence/persisted-model.decorator.js';
+import { SyncField } from '../../../core/modules/sync/core-sync.decorators.js';
+
+/**
+ * A note offered to offline clients — the reference implementation of a synchronized model
+ * (`src/core/modules/sync/INTEGRATION-CHECKLIST.md`).
+ *
+ * Not part of the reference server: `ServerModule` does not import it, so the framework's own suite runs without sync.
+ * The sync contract suite (`tests/sync-contract.e2e-spec.ts`) runs on exactly these files.
+ *
+ * - `sync.roles`: who may pull, create, change and delete through `/sync`. The roles of a project's own routes do not
+ *   reach the sync routes, so they are declared here; `S_CREATOR` is decided against the stored record.
+ * - `sync.strategy: 'merge'`: a change based on an older version keeps the fields the client changed — unless one of
+ *   them is `@SyncField('reject')`, which still conflicts.
+ * - `securityCheck()`: every user sees their own notes. A pull runs every record through it, a push decides with it
+ *   whether an id belongs to a record the caller may see.
+ */
+@PersistedModel({
+  sync: {
+    roles: {
+      create: [RoleEnum.S_USER],
+      delete: [RoleEnum.ADMIN, RoleEnum.S_CREATOR],
+      pull: [RoleEnum.S_USER],
+      update: [RoleEnum.ADMIN, RoleEnum.S_CREATOR],
+    },
+    strategy: 'merge',
+  },
+})
+@MongooseSchema({ timestamps: true })
+@ObjectType({ description: 'Note synchronized to offline clients' })
+@Restricted(RoleEnum.ADMIN)
+export class SyncNote extends CorePersistenceModel {
+  @UnifiedField({ description: 'Text of the note', isOptional: true, mongoose: true, roles: RoleEnum.S_EVERYONE })
+  body?: string = undefined;
+
+  /** Set by `CrudService.create()`; what `S_CREATOR` and `securityCheck()` decide on */
+  @UnifiedField({
+    description: 'ID of the user who created the note',
+    isOptional: true,
+    mongoose: { type: objectIdType() },
+    roles: RoleEnum.S_EVERYONE,
+    swaggerApiOptions: { type: String },
+    type: () => String,
+  })
+  createdBy?: string | Types.ObjectId = undefined;
+
+  /** A concurrent change of the priority is never merged silently: it answers `conflict` */
+  @SyncField('reject')
+  @UnifiedField({ description: 'Priority of the note', isOptional: true, mongoose: true, roles: RoleEnum.S_EVERYONE })
+  priority?: number = undefined;
+
+  @UnifiedField({ description: 'Title of the note', isOptional: true, mongoose: true, roles: RoleEnum.S_EVERYONE })
+  title?: string = undefined;
+
+  /** Every user sees the notes they created; administrators see all */
+  override securityCheck(user: any, force?: boolean) {
+    if (force || user?.hasRole?.([RoleEnum.ADMIN]) || (user?.id && equalIds(this.createdBy, user))) {
+      return this;
+    }
+    return undefined;
+  }
+}
+
+export const SyncNoteSchema = SchemaFactory.createForClass(SyncNote);

package/src/server/modules/sync-note/sync-note.module.ts

@@ -0,0 +1,16 @@
+import { Module } from '@nestjs/common';
+
+import { CorePersistenceModule } from '../../../core/common/persistence/core-persistence.module.js';
+import { SyncNote, SyncNoteSchema } from './sync-note.model.js';
+import { SyncNoteService } from './sync-note.service.js';
+
+/**
+ * The synchronized note model and its service. Registered with `CorePersistenceModule.forFeature()`, so the model
+ * follows `database` like every other — and only a model registered this way can be synchronized.
+ */
+@Module({
+  exports: [SyncNoteService],
+  imports: [CorePersistenceModule.forFeature([{ model: SyncNote, name: SyncNote.name, schema: SyncNoteSchema }])],
+  providers: [SyncNoteService],
+})
+export class SyncNoteModule {}

package/src/server/modules/sync-note/sync-note.service.ts

@@ -0,0 +1,25 @@
+import { Injectable } from '@nestjs/common';
+
+import type { DataStore } from '../../../core/common/persistence/data-store.interface.js';
+import { InjectStore } from '../../../core/common/persistence/inject-store.decorator.js';
+import { ConfigService } from '../../../core/common/services/config.service.js';
+import { CrudService } from '../../../core/common/services/crud.service.js';
+import { SyncService } from '../../../core/modules/sync/core-sync.decorators.js';
+import { SyncNoteCreateInput } from './inputs/sync-note-create.input.js';
+import { SyncNoteInput } from './inputs/sync-note.input.js';
+import { SyncNote } from './sync-note.model.js';
+
+/**
+ * The note service, offered to offline clients: `@SyncService()` puts the model under `/sync/SyncNote`, and every pull
+ * and push of it runs through this service — its `process()` pipeline, `securityCheck()`, the tenant policy.
+ */
+@SyncService({ createInput: SyncNoteCreateInput, model: SyncNote, updateInput: SyncNoteInput })
+@Injectable()
+export class SyncNoteService extends CrudService<SyncNote, SyncNoteCreateInput, SyncNoteInput> {
+  constructor(
+    protected override readonly configService: ConfigService,
+    @InjectStore(SyncNote) store: DataStore<SyncNote>,
+  ) {
+    super({ configService, dataStore: store, mainModelConstructor: SyncNote });
+  }
+}