The minimalistic document archiving platform.
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 echoRoute = defineApiRoute({
contract: defineApiContract({
operationId: 'echoUser',
method: 'POST',
path: '/api/users/:userId',
request: {
body: {
'application/json': v.strictObject({ name: v.pipe(v.string(), v.trim()) }),
},
query: v.object({ limit: v.pipe(v.string(), v.transform(Number)) }),
params: v.object({ userId: v.pipe(v.string(), v.startsWith('usr_')) }),
},
responses: {
201: {
description: 'Echoes the parsed request.',
content: {
'application/json': {
schema: v.object({
body: v.object({ name: v.string() }),
query: v.object({ limit: v.number() }),
params: v.object({ userId: v.string() }),
method: v.string(),
}),
},
},
},
},
}),
handler: async ({ body, query, params, request }) => ({
status: 201,
contentType: 'application/json',
body: { body, query, params, method: request.method },
headers: { 'X-Request-Id': 'request-1' },
}),
});
describe('buildApiRequestHandler', () => {
test('matched routes receive parsed input and return serialized responses', async () => {
const handleApiRequest = buildApiRequestHandler({ routes: [echoRoute] });
const response = await handleApiRequest({
request: new Request('https://papra.test/api/users/usr_123?limit=10', {
method: 'POST',
headers: { 'Content-Type': 'application/json; charset=utf-8' },
body: JSON.stringify({ name: ' Alice ' }),
}),
});
expect.assert(response);
expect(response.status).toEqual(201);
expect(response.headers.get('Content-Type')).toEqual('application/json');
expect(response.headers.get('X-Request-Id')).toEqual('request-1');
expect(await response.json()).toEqual({
body: { name: 'Alice' },
query: { limit: 10 },
params: { userId: 'usr_123' },
method: 'POST',
});
});
test('context resolves once per request before validation and is passed to the handler', async () => {
const events: string[] = [];
const handleApiRequest = buildApiRequestHandler({
routes: [
echoRoute,
defineApiRoute({
contract: defineApiContract({
...echoRoute.contract,
operationId: 'echoContext',
path: '/api/context/:userId',
request: {
params: v.pipe(
echoRoute.contract.request.params,
v.transform((params) => {
events.push('params');
return params;
}),
),
query: v.pipe(
echoRoute.contract.request.query,
v.transform((query) => {
events.push('query');
return query;
}),
),
body: {
'application/json': v.pipe(
echoRoute.contract.request.body['application/json'],
v.transform((body) => {
events.push('body');
return body;
}),
),
},
},
}),
resolveContext: async ({ request }) => {
events.push('resolve:start');
await Promise.resolve();
events.push('resolve:end');
return { requestId: request.headers.get('X-Request-Id') ?? 'unknown' };
},
handler: async ({ context, body, query, params, request }) => {
events.push('handler');
return {
status: 201,
contentType: 'application/json',
body: { body, query, params, method: request.method },
headers: { 'X-Request-Id': context.requestId },
};
},
}),
],
});
const sendRequest = async (requestId: string) =>
handleApiRequest({
request: new Request('https://papra.test/api/context/usr_123?limit=10', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Request-Id': requestId },
body: JSON.stringify({ name: ' Alice ' }),
}),
});
const firstResponse = await sendRequest('request-1');
const secondResponse = await sendRequest('request-2');
expect.assert(firstResponse);
expect.assert(secondResponse);
expect(firstResponse.status).toEqual(201);
expect(secondResponse.status).toEqual(201);
expect(firstResponse.headers.get('X-Request-Id')).toEqual('request-1');
expect(secondResponse.headers.get('X-Request-Id')).toEqual('request-2');
expect(await firstResponse.json()).toEqual({
body: { name: 'Alice' },
query: { limit: 10 },
params: { userId: 'usr_123' },
method: 'POST',
});
expect(events).toEqual([
'resolve:start',
'resolve:end',
'params',
'query',
'body',
'handler',
'resolve:start',
'resolve:end',
'params',
'query',
'body',
'handler',
]);
});
test('synchronous context resolvers provide their return value to the handler', async () => {
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
contract: defineApiContract({
operationId: 'getContext',
method: 'GET',
path: '/api/context',
responses: {
200: {
description: 'The resolved request path.',
content: { 'text/plain': { schema: v.string() } },
},
},
}),
resolveContext: ({ request }) => ({ path: new URL(request.url).pathname }),
handler: async ({ context }) => ({
status: 200,
contentType: 'text/plain',
body: context.path,
}),
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/context'),
});
expect.assert(response);
expect(response.status).toEqual(200);
expect(await response.text()).toEqual('/api/context');
});
test('resolver failures stop validation and the handler without exposing internal details', async () => {
let handlerCalled = false;
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
contract: echoRoute.contract,
resolveContext: async () => {
throw new Error('Sensitive resolver details');
},
handler: async () => {
handlerCalled = true;
throw new Error('The handler must not be called');
},
}),
],
});
const request = new Request('https://papra.test/api/users/invalid', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: 'Invalid JSON',
});
const response = await handleApiRequest({ request });
expect.assert(response);
expect(response.status).toEqual(500);
expect(await response.json()).toEqual({
error: { message: 'Internal server error', code: 'api.internal-error' },
});
expect(handlerCalled).toEqual(false);
expect(request.bodyUsed).toEqual(false);
});
test('public resolver errors return their status before validation or handler execution', async () => {
let handlerCalled = false;
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
contract: echoRoute.contract,
resolveContext: async () => {
throw createUnauthorizedError();
},
handler: async () => {
handlerCalled = true;
throw new Error('The handler must not be called');
},
}),
],
});
const request = new Request('https://papra.test/api/users/invalid', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: 'Invalid JSON',
});
const response = await handleApiRequest({ request });
expect.assert(response);
expect(response.status).toEqual(401);
expect(response.headers.get('Cache-Control')).toEqual('no-store');
expect(await response.json()).toEqual({
error: { message: 'Unauthorized', code: 'auth.unauthorized' },
});
expect(handlerCalled).toEqual(false);
expect(request.bodyUsed).toEqual(false);
});
test('public handler errors preserve their status and public payload without being cached', async () => {
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
contract: defineApiContract({
operationId: 'getError',
method: 'GET',
path: '/api/error',
responses: {},
}),
handler: async () => {
throw createError({
statusCode: 410,
message: 'Resource no longer available',
code: 'resource.gone',
cause: new Error('Sensitive cause'),
});
},
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/error'),
});
expect.assert(response);
expect(response.status).toEqual(410);
expect(response.headers.get('Content-Type')).toEqual('application/json');
expect(response.headers.get('Cache-Control')).toEqual('no-store');
expect(await response.json()).toEqual({
error: { message: 'Resource no longer available', code: 'resource.gone' },
});
});
test('internal custom errors are logged but return a sanitized non-cacheable 500', async () => {
const { logger, getLogs } = createTestLogger();
const error = createError({
statusCode: 503,
message: 'Sensitive internal details',
code: 'internal.sensitive',
isInternal: true,
});
const handleApiRequest = buildApiRequestHandler({
logger,
routes: [
defineApiRoute({
contract: defineApiContract({
operationId: 'getError',
method: 'GET',
path: '/api/error',
responses: {},
}),
handler: async () => {
throw error;
},
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/error'),
});
expect.assert(response);
expect(response.status).toEqual(500);
expect(response.headers.get('Cache-Control')).toEqual('no-store');
expect(await response.json()).toEqual({
error: { message: 'Internal server error', code: 'api.internal-error' },
});
expect(getLogs()).toMatchObject([
{ level: 'error', message: error.message, data: { error: { message: error.message } } },
]);
});
test('invalid request bodies return validation errors instead of reaching the handler', async () => {
const handleApiRequest = buildApiRequestHandler({ routes: [echoRoute] });
const response = await handleApiRequest({
request: new Request('https://papra.test/api/users/usr_123?limit=10', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 123 }),
}),
});
expect.assert(response);
expect(response.status).toEqual(400);
expect(response.headers.get('Cache-Control')).toEqual('no-store');
expect(await response.json()).toMatchObject({
error: {
code: 'api.validation_error',
details: [{ path: 'name' }],
},
});
});
test('invalid path parameters return validation errors instead of reaching the handler', async () => {
const handleApiRequest = buildApiRequestHandler({ routes: [echoRoute] });
const response = await handleApiRequest({
request: new Request('https://papra.test/api/users/invalid?limit=10', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Alice' }),
}),
});
expect.assert(response);
expect(response.status).toEqual(400);
expect(await response.json()).toMatchObject({
error: { code: 'api.validation_error', details: [{ path: 'userId' }] },
});
});
test('path parameter transformations reach the handler alongside heterogeneous routes', async () => {
const handleApiRequest = buildApiRequestHandler({
routes: [
echoRoute,
defineApiRoute({
contract: defineApiContract({
operationId: 'getPage',
method: 'GET',
path: '/api/pages/:page',
request: { params: v.object({ page: v.pipe(v.string(), v.transform(Number)) }) },
responses: {
200: {
description: 'The next page.',
content: { 'application/json': { schema: v.object({ nextPage: v.number() }) } },
},
},
}),
handler: async ({ params }) => ({
status: 200,
contentType: 'application/json',
body: { nextPage: params.page + 1 },
}),
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/pages/2'),
});
expect.assert(response);
expect(response.status).toEqual(200);
expect(await response.json()).toEqual({ nextPage: 3 });
});
test('absent schemas yield empty query and params objects and an undefined body', async () => {
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
contract: defineApiContract({
operationId: 'ignoreItem',
method: 'POST',
path: '/api/ignored/:id',
responses: { 204: { description: 'No content.', content: {} } },
}),
handler: async ({ body, query, params, context }) => {
expect({ body, query, params, context }).toEqual({
body: undefined,
query: {},
params: {},
context: undefined,
});
return { status: 204 };
},
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/ignored/123?limit=10', {
method: 'POST',
body: 'Ignored',
}),
});
expect.assert(response);
expect(response.status).toEqual(204);
expect(response.headers.get('Content-Type')).toEqual(null);
expect(await response.text()).toEqual('');
});
test('unmatched paths return undefined without resolving context or consuming the body', async () => {
let contextResolved = false;
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
...echoRoute,
resolveContext: () => {
contextResolved = true;
return undefined;
},
}),
],
});
const request = new Request('https://papra.test/api/missing', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: 'Invalid JSON',
});
const response = await handleApiRequest({ request });
expect(response).toEqual(undefined);
expect(contextResolved).toEqual(false);
expect(request.bodyUsed).toEqual(false);
expect(await request.text()).toEqual('Invalid JSON');
});
test('unmatched methods return undefined even when the path matches', async () => {
const handleApiRequest = buildApiRequestHandler({ routes: [echoRoute] });
const request = new Request('https://papra.test/api/users/usr_123?limit=10', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Alice' }),
});
const response = await handleApiRequest({ request });
expect(response).toEqual(undefined);
expect(request.bodyUsed).toEqual(false);
});
test('matched routes returning 404 produce a response instead of falling through', async () => {
const handleApiRequest = buildApiRequestHandler({
routes: [
defineApiRoute({
contract: defineApiContract({
operationId: 'getMissingDocument',
method: 'GET',
path: '/api/missing-document',
responses: {
404: {
description: 'The document does not exist.',
content: { 'text/plain': { schema: v.string() } },
},
},
}),
handler: async () => ({
status: 404,
contentType: 'text/plain',
body: 'Document not found',
}),
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/missing-document'),
});
expect.assert(response);
expect(response.status).toEqual(404);
expect(await response.text()).toEqual('Document not found');
});
test('unexpected handler failures are logged and return a generic error without exposing internal details', async () => {
const { logger, getLogs } = createTestLogger();
const error = new Error('Sensitive internal details');
const handleApiRequest = buildApiRequestHandler({
logger,
routes: [
defineApiRoute({
contract: defineApiContract({
operationId: 'getError',
method: 'GET',
path: '/api/error',
responses: {},
}),
handler: async () => {
throw error;
},
}),
],
});
const response = await handleApiRequest({
request: new Request('https://papra.test/api/error'),
});
expect.assert(response);
expect(response.status).toEqual(500);
expect(response.headers.get('Content-Type')).toEqual('application/json');
expect(response.headers.get('Cache-Control')).toEqual('no-store');
expect(await response.json()).toEqual({
error: { message: 'Internal server error', code: 'api.internal-error' },
});
expect(getLogs()).toMatchObject([
{ level: 'error', message: error.message, data: { error: { message: error.message } } },
]);
});
});