Merge pull request #264 from siberiacancode/prototype/sse

prototype/sse 🧊 add sse + move file handing into data handler

Author: MiaInturi

.husky/pre-commit

@@ -1 +1 @@
-pnpm run -r lint-staged
+pnpm -r --workspace-concurrency=1 run lint-staged

packages/playground/src/core/createDatabaseRoutes/storages/File/FileStorage.ts

@@ -8,9 +8,9 @@ import { APP_PATH } from '@/shared/constants';
 import { isIndex } from '../../helpers';
 import { FileWriter } from './FileWriter';
 
-export class FileStorage<
-  Data extends Record<StorageIndex, any> = Record<StorageIndex, any>
-> implements Storage {
+export class FileStorage<Data extends Record<StorageIndex, any> = Record<StorageIndex, any>>
+  implements Storage
+{
   private readonly fileWriter: FileWriter;
 
   private readonly data: Data;

packages/playground/src/core/createDatabaseRoutes/storages/Memory/MemoryStorage.ts

@@ -2,9 +2,9 @@ import type { Storage, StorageIndex } from '@/shared/types';
 
 import { isIndex } from '../../helpers';
 
-export class MemoryStorage<
-  Data extends Record<StorageIndex, any> = Record<StorageIndex, any>
-> implements Storage {
+export class MemoryStorage<Data extends Record<StorageIndex, any> = Record<StorageIndex, any>>
+  implements Storage
+{
   private readonly data: Data;
 
   public constructor(initialData: Data) {

packages/server/README.md

@@ -498,15 +498,9 @@ export default flatMockServerConfig;
 
 > If the file path is absolute, then this path will be used as is. If the file path is relative, it will be appended to the current working directory.
 
-If the file exists, response interceptors will receive `file descriptor` as the `data` argument:
+If the file exists, response interceptors will receive file content `Buffer` as the `data` argument.
 
-`File descriptor` is an object with `path` and `file` fields that describe file location and file content.
-
-- `path` `string` path to the file. Same as `file` passed in route
-- `file` `Buffer` file content as binary buffer
-
-> Note to return file descriptor from interceptor. Server will send a buffer from `data.file` with corresponding `Content-Type` and `Content-Disposition` headers.
-> If you return invalid file descriptor, server will send it as json data.
+`Content-Type` and `Content-Disposition` headers are set before response interceptors are called.
 
 ```javascript
 /** @type {import('mock-config-server').FlatMockServerConfig} */
@@ -523,11 +517,14 @@ const flatMockServerConfig = [
           {
             file: "./settings.json",
             interceptors: {
-              response: (data) => {
-                const { file, path } = data;
-                const buffer = file; // some logic with buffer
-                fs.writeFileSync(path, buffer); // rewrite ./settings.json file on disk with new content
-                return { path, file: buffer };
+              response: (data, { setHeader, getResponseHeader }) => {
+                // Content-Type and Content-Disposition are available before response interceptor runs.
+                console.log("Content-Type:", getResponseHeader("Content-Type"));
+                console.log("Content-Disposition:", getResponseHeader("Content-Disposition"));
+
+                const buffer = data;
+                const updatedBuffer = Buffer.from(buffer.toString("utf-8").replace("name", "title"));
+                return updatedBuffer;
               },
             },
           },
@@ -540,10 +537,6 @@ const flatMockServerConfig = [
 export default flatMockServerConfig;
 ```
 
-> Any changes to the data will not affect the file on disk unless you manually rewrite it.
-
-> If you return a new `path` from interceptor, server will send file corresponding to this path or 404 error otherwise.
-
 #### Polling
 
 Routes support polling for data. To add polling for data, you must specify the `polling setting` and use `queue` property instead of `data` or `file`.

packages/server/src/core/functions/rest/helpers/createFileHandler.ts

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { RestDataResponse, RestFileResponse, RestMethod } from '@/utils/types';
+
+import { isFilePathValid } from '@/utils/helpers';
+
+export const createFileHandler =
+  <Method extends RestMethod>(filePath: RestFileResponse): RestDataResponse<Method> =>
+  ({ response, setHeader, setStatusCode }) => {
+    if (!isFilePathValid(filePath)) {
+      // TODO: what should we do?
+      setStatusCode(404);
+      response.send('Not Found');
+      return null;
+    }
+
+    const buffer = fs.readFileSync(path.resolve(filePath));
+    const fileName = filePath.replaceAll('\\', '/').split('/').at(-1)!;
+    const fileExtension = fileName.split('.').at(-1)!;
+
+    response.type(fileExtension);
+    setHeader('Content-Disposition', `attachment; filename="${fileName}"`);
+
+    return buffer;
+  };

packages/server/src/core/functions/rest/helpers/formatSsePayload/formatSsePayload.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatSsePayload } from './formatSsePayload';
+
+describe('formatSsePayload', () => {
+  it('Should format payload without meta', () => {
+    const payload = formatSsePayload('hello');
+
+    expect(payload).toBe('data: hello\n\n');
+  });
+
+  it('Should include normalized meta fields before data', () => {
+    const payload = formatSsePayload('message', {
+      id: 'id\r\n123',
+      event: 'user\ncreated\r',
+      retry: 1500
+    });
+
+    expect(payload).toBe('id: id123\nevent: usercreated\nretry: 1500\ndata: message\n\n');
+  });
+
+  it('Should split multiline payload into multiple data lines', () => {
+    const payload = formatSsePayload('line1\r\nline2\nline3\rline4');
+
+    expect(payload).toBe('data: line1\ndata: line2\ndata: line3\ndata: line4\n\n');
+  });
+
+  it('Should throw if meta is invalid', () => {
+    expect(() => formatSsePayload('message', { retry: -1 })).toThrow(
+      'Invalid SSE meta: Number must be greater than or equal to 0'
+    );
+  });
+});

packages/server/src/core/functions/rest/helpers/formatSsePayload/formatSsePayload.ts

@@ -0,0 +1,48 @@
+import z from 'zod';
+
+const sseMetaSchema = z
+  .object({
+    event: z.string().optional(),
+    id: z.string().optional(),
+    retry: z.number().int().nonnegative().optional()
+  })
+  .optional();
+
+// ✅ important:
+// SSE is a line-based protocol. `id` and `event` must be single-line values.
+// Strip CR/LF so metadata cannot break frame structure.
+const normalizeSseMetaValue = (value: string) => value.replaceAll('\r', '').replaceAll('\n', '');
+
+export const formatSsePayload = (
+  data: string,
+  meta?: { event?: string; id?: string; retry?: number }
+) => {
+  const parseMetaResult = sseMetaSchema.safeParse(meta);
+  if (!parseMetaResult.success) {
+    throw new Error(`Invalid SSE meta: ${parseMetaResult.error.issues[0]?.message}`);
+  }
+
+  const parsedMeta = parseMetaResult.data;
+  const lines: string[] = [];
+
+  if (parsedMeta?.id) {
+    lines.push(`id: ${normalizeSseMetaValue(parsedMeta.id)}`);
+  }
+
+  if (parsedMeta?.event) {
+    lines.push(`event: ${normalizeSseMetaValue(parsedMeta.event)}`);
+  }
+
+  if (parsedMeta?.retry != null) {
+    lines.push(`retry: ${parsedMeta.retry}`);
+  }
+
+  // ✅ important:
+  // Multiline payloads are encoded as multiple `data:` lines.
+  // SSE clients concatenate consecutive `data:` lines with '\n' into one message.
+  data.split(/\r\n|\r|\n/).forEach((line) => {
+    lines.push(`data: ${line}`);
+  });
+
+  return `${lines.join('\n')}\n\n`;
+};

packages/server/src/core/functions/rest/helpers/index.ts

@@ -0,0 +1,2 @@
+export * from './createFileHandler';
+export * from './formatSsePayload/formatSsePayload';

packages/server/src/core/functions/rest/index.ts

@@ -0,0 +1 @@
+export * from './rest';

packages/server/src/core/functions/rest/rest.test.ts

@@ -60,7 +60,7 @@ describe('rest', () => {
       path: '/users',
       routes: [
         {
-          file: '/tmp/user.json',
+          data: expect.any(Function),
           entities: {
             headers: {
               key: 'value'
@@ -139,7 +139,7 @@ describe('rest', () => {
           queue: [
             { data: queueHandler, time: 100 },
             { data: { ok: 'response' }, time: 200 },
-            { file: '/tmp/user.json', time: 300 }
+            { data: expect.any(Function), time: 300 }
           ],
           entities: {
             headers: {
@@ -191,20 +191,92 @@ describe('rest', () => {
     });
   });
 
+  it('Should build config for SSE request', () => {
+    const result = rest.sse('/users/stream', () => undefined);
+
+    expect(result).toStrictEqual({
+      method: 'get',
+      path: '/users/stream',
+      routes: [
+        {
+          data: expect.any(Function),
+          settings: { polling: false }
+        }
+      ]
+    });
+  });
+
+  it('Should build config for stream request', () => {
+    const result = rest.stream('/users/stream', () => undefined);
+
+    expect(result).toStrictEqual({
+      method: 'post',
+      path: '/users/stream',
+      routes: [
+        {
+          data: expect.any(Function),
+          settings: { polling: false }
+        }
+      ]
+    });
+  });
+
+  it('Should send SSE payload and close stream client', async () => {
+    const result = rest.sse('/users/stream', ({ client }) => {
+      client.send('hello');
+      client.close();
+    });
+
+    const [route] = result.routes as [{ data: (params: any) => unknown }];
+    const routeData = route.data;
+    const setHeader = vi.fn();
+    const write = vi.fn();
+    const end = vi.fn();
+
+    await routeData({
+      setHeader,
+      response: { write, end }
+    });
+
+    expect(setHeader).toHaveBeenCalledTimes(3);
+    expect(setHeader).toHaveBeenNthCalledWith(1, 'connection', 'keep-alive');
+    expect(setHeader).toHaveBeenNthCalledWith(2, 'content-type', 'text/event-stream');
+    expect(setHeader).toHaveBeenNthCalledWith(3, 'cache-control', 'no-cache');
+    expect(write).toHaveBeenCalledWith('data: hello\n\n');
+    expect(end).toHaveBeenCalledTimes(1);
+  });
+
+  it('Should send SSE payload with meta fields', async () => {
+    const result = rest.sse('/users/stream', ({ client }) => {
+      client.send('msg', {
+        id: 'id-1',
+        event: 'user.created',
+        retry: 1500
+      });
+      client.close();
+    });
+
+    const [route] = result.routes as [{ data: (params: any) => unknown }];
+    const routeData = route.data;
+    const setHeader = vi.fn();
+    const write = vi.fn();
+    const end = vi.fn();
+
+    await routeData({
+      setHeader,
+      response: { write, end }
+    });
+
+    expect(write).toHaveBeenCalledWith('id: id-1\nevent: user.created\nretry: 1500\ndata: msg\n\n');
+  });
+
   it('Should type handler params with all typed fields', () => {
     const result = rest.post<{
       query: { query: string };
       body: { body: string };
       params: { params: string };
       response: { response: string };
-    }>('/users/:id', (params) => {
-      const query = params.request.query.query;
-      const body = params.request.body.body;
-      const path = params.request.params.params;
-      console.log(query, body, path);
-
-      return { response: 'value' };
-    });
+    }>('/users/:id', () => ({ response: 'value' }));
 
     expect(result).toStrictEqual({
       method: 'post',