🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
import { isPrismaException } from "@/src/utils/exceptions";
import { cors, runMiddleware } from "@/src/features/public-api/server/cors";
import { type NextApiRequest, type NextApiResponse } from "next";
import { type ZodError } from "zod";
import {
type BaseError,
isBaseError,
LangfuseNotFoundError,
MethodNotAllowedError,
UnauthorizedError,
type ApiDeprecationInfo,
} from "@langfuse/shared";
import {
logger,
traceException,
contextWithLangfuseProps,
ClickHouseResourceError,
} from "@langfuse/shared/src/server";
import * as opentelemetry from "@opentelemetry/api";
import {
sendStructuredPublicApiErrorResponse,
structuredPublicApiErrorContract,
toStructuredPublicApiError,
type PublicApiErrorContract,
} from "./structuredPublicApiErrorContract";
import { clickHouseRouteForRequest } from "@/src/features/public-api/server/clickHouseRequestTags";
import { setRetryAfterHeader } from "@/src/features/public-api/server/writeError";
import { withDeprecationResponse } from "@/src/features/public-api/server/deprecations";
import { env } from "@/src/env.mjs";
const httpMethods = ["GET", "POST", "PUT", "DELETE", "PATCH"] as const;
export type HttpMethod = (typeof httpMethods)[number];
/** RouteHandler is a method handler; `deprecation` marks it as a deprecated route. */
export type RouteHandler = ((
req: NextApiRequest,
res: NextApiResponse,
) => Promise<void>) & { deprecation?: ApiDeprecationInfo };
type Handlers = {
[Method in HttpMethod]?: RouteHandler;
};
const defaultHandler = () => {
throw new MethodNotAllowedError();
};
const DEFAULT_CLICKHOUSE_RESOURCE_ERROR_MESSAGE = [
ClickHouseResourceError.ERROR_ADVICE_MESSAGE,
"See https://langfuse.com/docs/api-and-data-platform/features/public-api for more details.",
].join("\n");
export const LEGACY_PUBLIC_API_OBSERVATIONS_CLICKHOUSE_RESOURCE_ERROR_MESSAGE =
[
ClickHouseResourceError.ERROR_ADVICE_MESSAGE,
"This legacy endpoint can be slow. Please migrate to the high-performance Observations API v2 at /api/public/v2/observations.",
"This applies to Langfuse Cloud only until v4 is released in OSS.",
"Docs: https://langfuse.com/docs/api-and-data-platform/features/observations-api",
].join("\n");
export const LEGACY_PUBLIC_API_METRICS_CLICKHOUSE_RESOURCE_ERROR_MESSAGE = [
ClickHouseResourceError.ERROR_ADVICE_MESSAGE,
"This legacy endpoint can be slow. Please migrate to the high-performance Metrics API v2 at /api/public/v2/metrics.",
"This applies to Langfuse Cloud only until v4 is released in OSS.",
"Docs: https://langfuse.com/docs/metrics/features/metrics-api",
].join("\n");
type MiddlewareOptions = {
errorContract?: PublicApiErrorContract;
clickHouseResourceErrorMessage?: string;
};
const logBaseError = (error: BaseError) => {
if (
error instanceof LangfuseNotFoundError ||
error instanceof UnauthorizedError
) {
logger.info(error);
return;
}
if (error.isUserError()) {
logger.warn(error);
return;
}
logger.error(error);
};
export function withMiddlewares(
handlers: Handlers,
options?: MiddlewareOptions,
) {
return async (req: NextApiRequest, nextRes: NextApiResponse) => {
const deprecation = deprecationForRequest(
handlers,
req.method as HttpMethod,
);
const res = deprecation
? withDeprecationResponse(nextRes, deprecation)
: nextRes;
const ctx = contextWithLangfuseProps({
headers: req.headers,
clickhouse: {
surface: "publicapi",
route: clickHouseRouteForRequest(req),
},
});
return opentelemetry.context.with(ctx, async () => {
try {
await runMiddleware(req, res, cors);
const method = req.method as HttpMethod;
if (!handlers[method]) throw new MethodNotAllowedError();
const finalHandlers: Required<Handlers> = {
...{
GET: defaultHandler,
POST: defaultHandler,
PUT: defaultHandler,
DELETE: defaultHandler,
PATCH: defaultHandler,
},
...handlers,
};
return await finalHandlers[method](req, res);
} catch (error) {
setRetryAfterHeader(res, error);
if (error instanceof ClickHouseResourceError) {
const errorMessage =
options?.clickHouseResourceErrorMessage ??
DEFAULT_CLICKHOUSE_RESOURCE_ERROR_MESSAGE;
logger.warn("ClickHouse resource limit exceeded", {
errorType: error.errorType,
message: error.message,
suggestion: errorMessage,
tags: error.tags,
});
if (options?.errorContract === structuredPublicApiErrorContract) {
return sendStructuredPublicApiErrorResponse(
res,
toStructuredPublicApiError(error),
);
}
return res.status(422).json({
message: errorMessage,
error: "Request timed out",
});
}
if (options?.errorContract === structuredPublicApiErrorContract) {
if (isBaseError(error)) {
logBaseError(error);
} else if (isZodError(error)) {
logger.warn(error);
} else {
logger.error(error);
}
if (isBaseError(error)) {
if (error.httpCode >= 500 && error.httpCode < 600) {
traceException(error);
}
} else if (!isZodError(error)) {
traceException(error);
}
return sendStructuredPublicApiErrorResponse(
res,
toStructuredPublicApiError(error),
);
}
if (isBaseError(error)) {
logBaseError(error);
if (error.httpCode >= 500 && error.httpCode < 600) {
traceException(error);
}
return res.status(error.httpCode).json({
message: error.message,
error: error.name,
});
}
if (isPrismaException(error)) {
logger.error(error);
traceException(error);
return res.status(500).json({
message: "Internal Server Error",
error: "An unknown error occurred",
});
}
// Instanceof check fails here as shared package zod has different instances
if (isZodError(error)) {
logger.warn(error);
return res.status(400).json({
message: "Invalid request data",
error: error.issues,
});
}
logger.error(error);
traceException(error);
return res.status(500).json({
message: "Internal Server Error",
error:
error instanceof Error
? error.message
: "An unknown error occurred",
});
}
});
};
}
/** deprecationForRequest returns the requested handler's deprecation on Cloud; for a method the route lacks, it returns one only when every handler is deprecated. */
function deprecationForRequest(
handlers: Handlers,
method: HttpMethod,
): ApiDeprecationInfo | undefined {
if (!env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION) return undefined;
const handler = handlers[method];
if (handler) return handler.deprecation;
const defined = Object.values(handlers).filter(
(h): h is RouteHandler => h !== undefined,
);
return defined.every((h) => h.deprecation)
? defined[0]?.deprecation
: undefined;
}
export function isZodError(error: any): error is ZodError {
return error instanceof Object && error.constructor.name === "ZodError";
}