✨ file download with json checking #294

trydofor · trydofor · commit 8deaf561791d · 2025-10-14T13:53:21.000+08:00
diff --git a/layers/common/composables/UseApiRouteFetcher.ts b/layers/common/composables/UseApiRouteFetcher.ts
@@ -116,6 +116,40 @@ export function apiResponseResultHook(includeFalse = true, id = 'responseResult'
   });
 }
 
+export function apiResponseDownloadHook(id = 'responseDownload'): ApiResponseHook & { id: string } {
+  return attachId(id, async (context) => {
+    const responseType = typeof context.options.responseType === 'string'
+      ? context.options.responseType.toLowerCase()
+      : undefined;
+    if (responseType !== 'blob') return;
+
+    const disposition = context.response.headers.get('content-disposition');
+    const currentData = context.response._data;
+    if (isFileResult(currentData)) return;
+    if (!isBlobLike(currentData)) return;
+
+    if (disposition != null && /attachment/i.test(disposition)) {
+      const name = parseContentDispositionFilename(disposition) ?? 'download.bin';
+      context.response._data = {
+        name,
+        blob: currentData,
+      } satisfies FileResult;
+      return;
+    }
+
+    const text = await currentData.text();
+    if (text) {
+      const json = JSON.parse(text);
+      context.response._data = (json != null && typeof json === 'object')
+        ? json
+        : { success: false, message: text };
+    }
+    else {
+      context.response._data = { success: false };
+    }
+  });
+}
+
 export function isFetchError(err: unknown): err is FetchError {
   return err instanceof FetchError;
 }
@@ -124,6 +158,7 @@ export const defaultFetchHooks = {
   requestAcceptContent: apiRequestAcceptContentHook(),
   responseSession: apiResponseSessionHook(),
   responseStatus: apiResponseStatusHook(),
+  responseDownload: apiResponseDownloadHook(),
   responseResult: apiResponseResultHook(),
 };
 
@@ -154,6 +189,7 @@ export const defaultFetchOptions: FetchOptions = {
   onResponse: [
     defaultFetchHooks.responseSession,
     defaultFetchHooks.responseStatus,
+    defaultFetchHooks.responseDownload,
     defaultFetchHooks.responseResult,
   ],
 };
diff --git a/layers/common/tests/UseApiRouteFetcher.test.ts b/layers/common/tests/UseApiRouteFetcher.test.ts
@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer';
 import { registerEndpoint } from '@nuxt/test-utils/runtime';
 import { describe, expect, it, vi } from 'vitest';
 
@@ -19,6 +20,39 @@ registerEndpoint('/api/v1/test-post.json', (event) => {
   return { success: true, data: contentType ?? null };
 });
 
+registerEndpoint('/api/v1/test-download.json', (event) => {
+  const url = event.node.req.url != null ? new URL(event.node.req.url, 'http://localhost') : null;
+  const filename = url?.searchParams.get('f')?.trim();
+  const useStar = url?.searchParams.get('star') === '1';
+  const fallback = url?.searchParams.get('fb') ?? filename ?? '';
+
+  if (!filename) {
+    return {
+      success: false,
+      errors: [{ message: 'filename required' }],
+    };
+  }
+
+  const disposition: string[] = ['attachment'];
+  if (useStar) {
+    disposition.push(`filename="${fallback || 'download.bin'}"`);
+    disposition.push(`filename*=UTF-8''${encodeURIComponent(filename)}`);
+  }
+  else {
+    disposition.push(`filename="${filename}"`);
+  }
+
+  event.node.res.setHeader('Content-Disposition', disposition.join('; '));
+  event.node.res.setHeader('Content-Type', 'application/octet-stream');
+
+  return Buffer.from(`download:${filename}`, 'utf-8');
+});
+
+registerEndpoint('/api/v1/test-put.json', (event) => {
+  const contentType = event.node.req.headers['content-type'];
+  return { success: true, data: contentType ?? null };
+});
+
 registerEndpoint('/api/v1/test-403.json', (event) => {
   event.node.res.statusCode = 403;
   return { error: 'Forbidden' };
@@ -49,6 +83,12 @@ registerEndpoint('/api/v1/test-false.json', () => {
 });
 
 describe('useApiRouteFetcher with real $fetch requests', () => {
+  it('should include download hook by default', () => {
+    const { opt } = useApiRouteFetcher();
+    const hooks = (opt().onResponse as SafeAny[] | undefined)?.map((fn: SafeAny) => fn.id ?? 'unknown');
+    expect(hooks).toContain('responseDownload');
+  });
+
   it('should send GET request with correct Content-Type (no body)', async () => {
     const { get, raw } = useApiRouteFetcher();
     const rs1 = await get('/test-get.json');
@@ -70,6 +110,60 @@ describe('useApiRouteFetcher with real $fetch requests', () => {
     expect(rs2._data).toEqual({ success: true, data: 'application/json' });
   });
 
+  it('should send PUT request with JSON Content-Type via req', async () => {
+    const { req } = useApiRouteFetcher();
+    const rs = await req<unknown, SafeAny>('/test-put.json', { method: 'put', body: { key: 'value' } });
+    logger.debug('put JSON', JSON.stringify(rs));
+    expect(rs.data).toBe('application/json');
+  });
+
+  it('should download file when query filename provided', async () => {
+  const { raw, req } = useApiRouteFetcher();
+  const rs = await raw<unknown, SafeAny>('/test-download.json', {
+    method: 'get',
+    query: { f: 'report.txt' },
+    responseType: 'blob',
+  });
+    const headers = Object.fromEntries(rs.headers.entries());
+    const file = rs._data as FileResult;
+    expect(headers['content-disposition']).toBe('attachment; filename="report.txt"');
+    expect(headers['content-type']).toBe('application/octet-stream');
+    expect(file.name).toBe('report.txt');
+    expect(Object.prototype.toString.call(file.blob)).toBe('[object Blob]');
+    await expect(file.blob.text()).resolves.toBe('download:report.txt');
+
+  const direct = await req<unknown, SafeAny>('/test-download.json', {
+    method: 'get',
+    query: { f: 'report.txt' },
+    responseType: 'blob',
+  });
+    expect((direct as FileResult).name).toBe('report.txt');
+  });
+
+  it('should prefer filename* when provided', async () => {
+    const { raw } = useApiRouteFetcher();
+  const rs = await raw<unknown, SafeAny>('/test-download.json', {
+    method: 'get',
+    query: { f: '报告.txt', star: '1', fb: 'fallback.txt' },
+    responseType: 'blob',
+  });
+    const file = rs._data as FileResult;
+    expect(file.name).toBe('报告.txt');
+    expect(Object.prototype.toString.call(file.blob)).toBe('[object Blob]');
+    await expect(file.blob.text()).resolves.toBe('download:报告.txt');
+  });
+
+  it('should fail download when filename query missing', async () => {
+    const { req } = useApiRouteFetcher();
+  await expect(req('/test-download.json', {
+    responseType: 'blob',
+  })).rejects.toSatisfy((error: SafeAny) => {
+      return error instanceof ApiResultError
+        && error.errorResult != null
+        && error.errorResult.errors?.[0]?.message === 'filename required';
+    });
+  });
+
   it('should send POST request with FormData Content-Type', async () => {
     const { post } = useApiRouteFetcher();
     const formData = new FormData();
diff --git a/layers/common/tests/typed-fetcher.test.ts b/layers/common/tests/typed-fetcher.test.ts
@@ -3,6 +3,7 @@
 const mockDataResult: DataResult<string> = { success: true, data: 'test data' };
 const mockPageResult: PageResult<string> = { success: true, data: ['test data'], page: 1, size: 10, totalPage: 1, totalData: 1 };
 const mockErrorResult: ErrorResult = { success: false, errors: [{ type: 'Validation', target: 'field', message: 'Invalid input' }] };
+const mockFileResult: FileResult = { name: 'file.txt', blob: new Blob(['file']) };
 
 describe('typed-fetcher', () => {
   it('should update loading state correctly', async () => {
@@ -66,6 +67,13 @@ describe('typed-fetcher', () => {
     expect(result).toEqual({ success: true, data: 'transformed' });
   });
 
+  it('fetchFileResult should return FileResult', async () => {
+    const fetching = vi.fn().mockResolvedValue(mockFileResult);
+    const result = await fetchFileResult(fetching);
+    expect(fetching).toHaveBeenCalled();
+    expect(result).toEqual(mockFileResult);
+  });
+
   it('getDataResult should return DataResult if valid', () => {
     expect(isDataResult(mockDataResult)).toBe(true);
     expect(isDataResult(mockPageResult)).toBe(true);
diff --git a/layers/common/utils/common-blob.ts b/layers/common/utils/common-blob.ts
@@ -0,0 +1,93 @@
+/**
+ * Save blob to file with filename
+ */
+export function saveBlobFile(blob: FileResult | Blob, name = 'download.blob'): void {
+  const result = isFileResult(blob);
+  const fileName = result ? blob.name : name;
+  const fileBlob = result ? blob.blob : blob;
+  const nav = window.navigator as Navigator & { msSaveOrOpenBlob?: (blob: Blob, name?: string) => void };
+  if (typeof nav?.msSaveOrOpenBlob === 'function') {
+    nav.msSaveOrOpenBlob(fileBlob, fileName);
+    return;
+  }
+
+  const link = document.createElement('a');
+  const blobUrl = URL.createObjectURL(fileBlob);
+
+  try {
+    link.style.display = 'none';
+    link.href = blobUrl;
+    link.setAttribute('download', fileName);
+    link.setAttribute('target', '_blank');
+
+    document.body.appendChild(link);
+
+    let event: MouseEvent;
+    try {
+      event = new MouseEvent('click');
+    }
+    catch {
+      // fallback
+      event = document.createEvent('MouseEvent');
+      event.initMouseEvent('click', true, true, window, 0, 0, 0, 0, 0, false, false, false, false, 0, null);
+    }
+
+    link.dispatchEvent(event);
+  }
+  finally {
+    setTimeout(() => {
+      if (link.parentNode) {
+        link.parentNode.removeChild(link);
+      }
+      (window.URL || window.webkitURL || window).revokeObjectURL(blobUrl);
+    }, 10_000);
+  }
+}
+
+export function parseContentDispositionFilename(disposition: string): string | undefined {
+  let fallbackName: string | undefined;
+  for (const part of disposition.split(';')) {
+    const equalsIndex = part.indexOf('=');
+    if (equalsIndex === -1) continue;
+
+    const key = part.slice(0, equalsIndex).trim().toLowerCase();
+    let value = part.slice(equalsIndex + 1).trim();
+
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    }
+
+    if (key === 'filename*') {
+      const match = value.match(/^(.*?)'(?:.*)'(.*)$/);
+      const encoded = match ? match[2] : value;
+      try {
+        const decoded = decodeURIComponent(encoded);
+        if (decoded) return decoded;
+      }
+      catch {
+        if (encoded) return encoded;
+      }
+    }
+    else if (key === 'filename') {
+      fallbackName = value;
+    }
+  }
+
+  if (fallbackName != null && fallbackName !== '') {
+    try {
+      return decodeURIComponent(fallbackName);
+    }
+    catch {
+      return fallbackName;
+    }
+  }
+
+  return undefined;
+}
+
+export function isBlobLike(data: SafeAny): data is Blob {
+  return data != null
+    && typeof data === 'object'
+    && typeof data.arrayBuffer === 'function'
+    && typeof data.text === 'function';
+}
diff --git a/layers/common/utils/common-notify.ts b/layers/common/utils/common-notify.ts
diff --git a/layers/common/utils/common-result.ts b/layers/common/utils/common-result.ts
@@ -58,6 +58,15 @@ export interface PageResult<T = unknown> extends DataResult<T[]> {
 
 export type ApiResult<T = unknown> = DataResult<T> | PageResult<T> | ErrorResult;
 
+/**
+ * * name: file name
+ * * blob: file content
+ */
+export interface FileResult {
+  name: string;
+  blob: Blob;
+};
+
 export function isDataResult<T>(result?: ApiResult<T> | null): result is DataResult<T> {
   return result != null && !('errors' in result);
 }
@@ -87,3 +96,16 @@ export function mustPageResult<T>(result?: ApiResult<T> | null): PageResult<T> {
 export function isErrorResult(result?: ApiResult<SafeAny> | null): result is ErrorResult {
   return (result != null && 'errors' in result);
 }
+
+export function isFileResult(result?: SafeAny | null): result is FileResult {
+  return (result != null && 'name' in result && 'blob' in result);
+}
+
+export function mustFileResult(result?: SafeAny | null): FileResult {
+  if (isFileResult(result)) {
+    return result;
+  }
+  else {
+    throw new SystemError('require FileResult', result);
+  }
+}
diff --git a/layers/common/utils/typed-fetcher.ts b/layers/common/utils/typed-fetcher.ts
@@ -53,6 +53,18 @@ export async function fetchTypedPage<T>(
   const result = await fetchTypedResult(fetching, options);
   return mustPageResult(result);
 }
+
+/**
+ * downloading file with loading, result, error handling
+ */
+export async function fetchFileResult(
+  fetching: Promise<SafeAny> | (() => Promise<SafeAny>),
+  options: TypedFetchOptions<SafeAny> | Ref<boolean> = globalLoadingStatus,
+): Promise<FileResult> {
+  const result = await fetchTypedResult(fetching, options);
+  return mustFileResult(result);
+}
+
 /**
  * fetching any result with loading, result, error handling
  *
diff --git a/plays/1-play-spa/server/api/v1/download.ts b/plays/1-play-spa/server/api/v1/download.ts
@@ -1,4 +1,5 @@
 import { Readable } from 'stream';
+import { getQuery } from 'h3';
 
 // https://nuxt.com/docs/guide/directory-structure/server
 
@@ -17,15 +18,39 @@ import { Readable } from 'stream';
  * ```
  */
 export default defineEventHandler(async (event) => {
+  const query = getQuery(event);
+  const queryValue = query.f ?? query.filename;
+  const rawFilename = Array.isArray(queryValue) ? queryValue[0] : queryValue;
+  const filename = rawFilename?.toString().trim();
+
+  if (!filename) {
+    return {
+      success: false,
+      errors: [{ message: 'Filename is required' }],
+    };
+  }
+
+  const content = typeof query.content === 'string' && query.content !== ''
+    ? query.content
+    : `download:${filename}`;
+
   const stream = new Readable({
     read() {
-      this.push('download.txt');
+      this.push(content);
       this.push(null);
     },
   });
 
-  event.node.res.setHeader('Content-Disposition', 'attachment; filename="download.txt"');
-  event.node.res.setHeader('Content-Type', 'text/plain');
+  const hasNonAscii = /[^\x20-\x7E]/.test(filename);
+  const safeName = filename.replace(/"/g, '%22');
+  const fallbackName = hasNonAscii ? 'download.bin' : safeName;
+  const disposition: string[] = ['attachment', `filename="${fallbackName}"`];
+  if (hasNonAscii) {
+    disposition.push(`filename*=UTF-8''${encodeURIComponent(filename)}`);
+  }
+
+  event.node.res.setHeader('Content-Disposition', disposition.join('; '));
+  event.node.res.setHeader('Content-Type', 'application/octet-stream');
 
   return sendStream(event, stream);
 });
diff --git a/plays/2-play-web/pages/15-download.vue b/plays/2-play-web/pages/15-download.vue
