Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

11.1 KB
Raw Blame
import * as v from 'valibot';
import { describe, expect, test } from 'vitest';
import { createUnauthorizedError } from '../app/auth/auth.errors';
import { createError } from '../shared/errors/errors';
import { createTestLogger } from '../shared/logger/logger.test-utils';
import { defineApiContract } from './api.contracts';
import { buildApiRequestHandler } from './api.request-handler';
import { defineApiRoute } from './api.routes';

const getDocumentRoute = defineApiRoute({
  contract: defineApiContract({
    operationId: 'getDocument',
    method: 'GET',
    path: '/api/documents/:documentId',
    request: {
      params: v.object({ documentId: v.pipe(v.string(), v.startsWith('doc_')) }),
      query: v.object({ format: v.optional(v.literal('text')) }),
    },
    responses: {
      200: {
        description: 'The document content.',
        content: { 'text/plain': { schema: v.string() } },
      },
      404: {
        description: 'The document does not exist.',
        content: { 'text/plain': { schema: v.string() } },
      },
    },
  }),
  handler: async () => ({
    status: 200,
    contentType: 'text/plain',
    body: 'Hello',
    headers: { 'Content-Length': '5', 'ETag': '"v1"', 'X-Route': 'get' },
  }),
});

const headDocumentContract = defineApiContract({
  ...getDocumentRoute.contract,
  operationId: 'headDocument',
  method: 'HEAD',
  responses: {
    200: { description: 'The document metadata.', content: {} },
    404: { description: 'The document does not exist.', content: {} },
  },
});

describe('HEAD request handling', () => {
  test('explicit HEAD routes take precedence over GET without changing GET behavior', async () => {
    const handleApiRequest = buildApiRequestHandler({
      routes: [
        getDocumentRoute,
        defineApiRoute({
          contract: headDocumentContract,
          handler: async () => ({
            status: 200,
            headers: {
              'Content-Type': 'text/plain',
              'Content-Length': '5',
              'ETag': '"v1"',
              'X-Route': 'head',
            },
          }),
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123', { method: 'HEAD' }),
    });
    const getResponse = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123'),
    });

    expect.assert(response);
    expect(response.status).toEqual(200);
    expect(response.headers.get('X-Route')).toEqual('head');
    expect(response.headers.get('Content-Type')).toEqual('text/plain');
    expect(response.headers.get('Content-Length')).toEqual('5');
    expect(response.headers.get('ETag')).toEqual('"v1"');
    expect(response.body).toEqual(null);
    expect(await response.text()).toEqual('');
    expect.assert(getResponse);
    expect(getResponse.status).toEqual(200);
    expect(getResponse.headers.get('X-Route')).toEqual('get');
    expect(await getResponse.text()).toEqual('Hello');
  });

  test('GET fallback validates inputs and passes the original HEAD request through context and handler', async () => {
    const seenRequests: Request[] = [];
    const handleApiRequest = buildApiRequestHandler({
      routes: [
        defineApiRoute({
          contract: getDocumentRoute.contract,
          resolveContext: ({ request }) => {
            seenRequests.push(request);
            return { method: request.method };
          },
          handler: async (input) => {
            seenRequests.push(input.request);
            expect(input.context).toEqual({ method: 'HEAD' });
            expect(input.params).toEqual({ documentId: 'doc_123' });
            expect(input.query).toEqual({ format: 'text' });
            expect(input.body).toEqual(undefined);
            return getDocumentRoute.handler({ ...input, context: undefined });
          },
        }),
      ],
    });
    const request = new Request('https://papra.test/api/documents/doc_123?format=text', {
      method: 'HEAD',
    });

    const response = await handleApiRequest({ request });

    expect.assert(response);
    expect(response.status).toEqual(200);
    expect(response.headers.get('X-Route')).toEqual('get');
    expect(response.headers.get('Content-Type')).toEqual('text/plain; charset=utf-8');
    expect(response.headers.get('Content-Length')).toEqual('5');
    expect(response.headers.get('ETag')).toEqual('"v1"');
    expect(response.body).toEqual(null);
    expect(await response.text()).toEqual('');
    expect(seenRequests.map((seenRequest) => seenRequest === request)).toEqual([true, true]);
  });

  test('a matched HEAD route returning 404 does not retry GET or fall through', async () => {
    const handleApiRequest = buildApiRequestHandler({
      routes: [
        getDocumentRoute,
        defineApiRoute({
          contract: headDocumentContract,
          handler: async () => ({ status: 404, headers: { 'X-Route': 'head' } }),
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(404);
    expect(response.headers.get('X-Route')).toEqual('head');
    expect(response.body).toEqual(null);
  });

  test('a matched GET fallback returning 404 stays final and loses its body', async () => {
    const handleApiRequest = buildApiRequestHandler({
      routes: [
        defineApiRoute({
          contract: getDocumentRoute.contract,
          handler: async () => ({ status: 404, contentType: 'text/plain', body: 'Not found' }),
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(404);
    expect(response.headers.get('Content-Type')).toEqual('text/plain; charset=utf-8');
    expect(response.body).toEqual(null);
  });

  test('invalid HEAD path parameters return a bodyless validation error', async () => {
    const handleApiRequest = buildApiRequestHandler({ routes: [getDocumentRoute] });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/invalid', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(400);
    expect(response.headers.get('Cache-Control')).toEqual('no-store');
    expect(response.body).toEqual(null);
  });

  test('invalid HEAD query parameters return a bodyless validation error', async () => {
    const handleApiRequest = buildApiRequestHandler({ routes: [getDocumentRoute] });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123?format=json', {
        method: 'HEAD',
      }),
    });

    expect.assert(response);
    expect(response.status).toEqual(400);
    expect(response.headers.get('Cache-Control')).toEqual('no-store');
    expect(response.body).toEqual(null);
  });

  test('GET fallback body parsing failures return bodyless responses', async () => {
    const handleApiRequest = buildApiRequestHandler({
      routes: [
        defineApiRoute({
          contract: defineApiContract({
            ...getDocumentRoute.contract,
            request: { body: { 'application/json': v.object({ name: v.string() }) } },
          }),
          handler: async () => ({ status: 200, contentType: 'text/plain', body: 'Hello' }),
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(415);
    expect(response.headers.get('Cache-Control')).toEqual('no-store');
    expect(response.body).toEqual(null);
  });

  test('HEAD authentication failures preserve their status and headers without a body', async () => {
    const { logger } = createTestLogger();
    const handleApiRequest = buildApiRequestHandler({
      logger,
      routes: [
        defineApiRoute({
          ...getDocumentRoute,
          resolveContext: () => {
            throw createUnauthorizedError();
          },
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/invalid', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(401);
    expect(response.headers.get('Content-Type')).toEqual('application/json');
    expect(response.headers.get('Cache-Control')).toEqual('no-store');
    expect(response.body).toEqual(null);
  });

  test('public HEAD handler errors preserve their status without a body', async () => {
    const { logger } = createTestLogger();
    const handleApiRequest = buildApiRequestHandler({
      logger,
      routes: [
        defineApiRoute({
          contract: getDocumentRoute.contract,
          handler: async () => {
            throw createError({ statusCode: 410, message: 'Gone', code: 'document.gone' });
          },
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(410);
    expect(response.headers.get('Cache-Control')).toEqual('no-store');
    expect(response.body).toEqual(null);
  });

  test('unexpected HEAD handler failures return a bodyless non-cacheable 500', async () => {
    const { logger } = createTestLogger();
    const handleApiRequest = buildApiRequestHandler({
      logger,
      routes: [
        defineApiRoute({
          contract: headDocumentContract,
          handler: async () => {
            throw new Error('Sensitive details');
          },
        }),
      ],
    });

    const response = await handleApiRequest({
      request: new Request('https://papra.test/api/documents/doc_123', { method: 'HEAD' }),
    });

    expect.assert(response);
    expect(response.status).toEqual(500);
    expect(response.headers.get('Cache-Control')).toEqual('no-store');
    expect(response.body).toEqual(null);
  });

  test('HEAD requests without a HEAD or GET match fall through without resolving context', async () => {
    let contextResolved = false;
    const handleApiRequest = buildApiRequestHandler({
      routes: [
        defineApiRoute({
          contract: defineApiContract({
            operationId: 'createDocument',
            method: 'POST',
            path: '/api/documents',
            responses: { 204: { description: 'Created.', content: {} } },
          }),
          resolveContext: () => {
            contextResolved = true;
          },
          handler: async () => ({ status: 204 }),
        }),
      ],
    });

    const unmatchedMethodResponse = await handleApiRequest({
      request: new Request('https://papra.test/api/documents', { method: 'HEAD' }),
    });
    const unmatchedPathResponse = await handleApiRequest({
      request: new Request('https://papra.test/api/missing', { method: 'HEAD' }),
    });

    expect(unmatchedMethodResponse).toEqual(undefined);
    expect(unmatchedPathResponse).toEqual(undefined);
    expect(contextResolved).toEqual(false);
  });
});