@lenne.tech/nest-server 12.1.1 → 12.3.0

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 });
+  }
+}

package/src/test/test.helper.ts

@@ -7,6 +7,7 @@ import * as util from 'util';
 import ws from 'ws';
 
 import { getStringIds } from '../core/common/helpers/db.helper.js';
+import { ConfigService } from '../core/common/services/config.service.js';
 import { resolveBetterAuthSessionCookieName } from '../core/modules/better-auth/better-auth-cookie-prefix.helper.js';
 import { isObjectIdLike } from '../core/common/helpers/id.helper.js';
 
@@ -239,6 +240,12 @@ export interface TestMcpOptions {
  * Options for `testHelper.mcpSession()`
  */
 export interface TestMcpSessionOptions extends Omit<TestMcpOptions, 'sessionId' | 'statusCode'> {
+  /**
+   * Whether the server runs without sessions; then no session id is expected or sent, and
+   * `close()` does nothing. Defaults to `ai.mcp.stateless` of the running configuration.
+   */
+  stateless?: boolean;
+
   /**
    * `clientInfo` sent with `initialize`. Default: `{ name: 'nest-server-test-helper', version: '1.0.0' }`
    */
@@ -342,7 +349,7 @@ export interface TestMcpSession {
   ): Promise<null | TestMcpMessage>;
 
   /**
-   * `mcp-session-id` the server assigned
+   * `mcp-session-id` the server assigned; `''` on a stateless server (`ai.mcp.stateless`)
    */
   sessionId: string;
 }
@@ -697,8 +704,12 @@ export class TestHelper {
       base,
     );
     expect(init.message?.error).toBeUndefined();
-    expect(init.sessionId).toBeTruthy();
-    const sessionId = init.sessionId;
+    // A stateless server (`ai.mcp.stateless`) issues no session id; every request stands alone there.
+    const stateless = options.stateless ?? ConfigService.get<{ stateless?: boolean }>('ai.mcp')?.stateless === true;
+    if (!stateless) {
+      expect(init.sessionId).toBeTruthy();
+    }
+    const sessionId: string = stateless ? '' : (init.sessionId ?? '');
     await this.mcp({ method: 'notifications/initialized' }, { ...base, sessionId });
 
     let nextId = 2;
@@ -718,6 +729,9 @@ export class TestHelper {
         return { ...result, json: TestHelper.parseJsonOrUndefined(result.content?.[0]?.text) };
       },
       close: async () => {
+        if (!sessionId) {
+          return;
+        }
         await this.rest(path, {
           cookies: base.cookies,
           headers: { ...base.headers, 'mcp-session-id': sessionId },