`/concepts/idp-brokering` 이 「페이지를 찾을 수 없습니다」였다. API 도 라우트도 200 인데 화면만 404 였고, 콘솔을 보니 개념 화면이 `/api/v1/public/questions/idp-brokering` 을 부르고 있었다. 세 가지가 겹쳤다. 계약 타입에는 getPublicConcept 이 있었지만 기여 목록에 등록되지 않아 부를 수 없었다. 게이트웨이는 종류를 삼항으로 이어 붙여 마지막 else 가 남은 것을 다 질문 조회로 보냈다. 응답을 기록으로 바꾸는 분기에도 개념이 없어, 설령 불렸어도 질문 매핑으로 떨어졌을 것이다. 개념 삭제에서 겪은 것과 같은 모양이다 — 손으로 나열한 분기의 마지막 else 가 새 종류를 조용히 삼킨다. 표로 두어 종류가 늘면 타입이 잡게 하고, 네 종류가 각각 자기 주소로 나가는지 확인하는 가드를 둔다. 개념 본문은 Case 와 같은 규칙을 쓴다(Markdown 한 덩어리 + `:::evidence`). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
173 lines
6.9 KiB
TypeScript
173 lines
6.9 KiB
TypeScript
import type {
|
|
InstalledContractContribution,
|
|
InstalledHttpContract,
|
|
} from "../../../contracts/external-contract-runtime.ts";
|
|
import { TECH_LOG_FEATURE_ID } from "../application/tech-log-feature-input.ts";
|
|
import canonicalSource from "./public/canonical-source.json" with { type: "json" };
|
|
import { envelopeData, envelopeError, passthroughInput } from "./tech-log-studio-contract-contribution.ts";
|
|
|
|
type PathValues = Readonly<Record<string, string>>;
|
|
type QueryEntries = readonly (readonly [string, string])[];
|
|
|
|
const NO_PATH: PathValues = Object.freeze({});
|
|
const NO_QUERY = Object.freeze([]) as QueryEntries;
|
|
/**
|
|
* public-v1.yaml `ApiError.code` enum과 1:1이다. `INTERNAL_ERROR` 는 이 기능이
|
|
* 아니라 스켈레톤 공통 처리기가 내는 코드이고, 계약이 그것까지 열거하므로 여기도
|
|
* 열거한다 — 빠지면 500 응답이 계약 위반으로 분류된다.
|
|
*/
|
|
const PUBLIC_ERROR_CODES = Object.freeze([
|
|
"PUBLIC_REQUEST_INVALID",
|
|
"PUBLIC_RESOURCE_NOT_FOUND",
|
|
"INTERNAL_ERROR",
|
|
]);
|
|
|
|
const PROBLEM = envelopeError(PUBLIC_ERROR_CODES, "PublicErrorEnvelope");
|
|
|
|
function queryOf(input: Readonly<Record<string, unknown>>): QueryEntries {
|
|
const entries: (readonly [string, string])[] = [];
|
|
for (const [key, value] of Object.entries(input)) {
|
|
if (value === undefined || value === null || value === "") continue;
|
|
entries.push([key, String(value)]);
|
|
}
|
|
return Object.freeze(entries);
|
|
}
|
|
|
|
/**
|
|
* Every public operation has the same shape, which is the point of holding this
|
|
* surface apart from Studio: all 18 are GET, none carries a body, none needs a
|
|
* session, and none needs a CSRF token. The `ANONYMOUS` auth profile is what
|
|
* states that — it forbids credentials outright, so a future change that starts
|
|
* sending the session cookie on a public read fails the profile check rather
|
|
* than silently making the cache-friendly surface user-specific.
|
|
*/
|
|
function publicRead(
|
|
operationId: string,
|
|
pathTemplate: string,
|
|
responseByteLimit: number,
|
|
project: (input: never) => Readonly<{ pathValues: PathValues; queryEntries: QueryEntries }> = () =>
|
|
Object.freeze({ pathValues: NO_PATH, queryEntries: NO_QUERY }),
|
|
): InstalledHttpContract<unknown, unknown, unknown> {
|
|
return Object.freeze({
|
|
contract: Object.freeze({
|
|
operationId,
|
|
method: "GET" as const,
|
|
pathTemplate,
|
|
inputValidator: passthroughInput(`${operationId}Input`),
|
|
outputValidator: envelopeData(`${operationId}Output`),
|
|
problemValidator: PROBLEM,
|
|
// 404 is a normal answer here — a slug that is not published — so it is
|
|
// mapped by the gateway rather than treated as a transport failure.
|
|
acceptedStatuses: Object.freeze([200]),
|
|
emptyBodyStatuses: Object.freeze([]),
|
|
retrySemantics: "SAFE" as const,
|
|
requestBody: "NONE" as const,
|
|
responseBody: "REQUIRED_JSON" as const,
|
|
commandRecovery: null,
|
|
commandEffect: null,
|
|
projectRequest(input: never) {
|
|
return Object.freeze({ ...project(input), body: null });
|
|
},
|
|
}),
|
|
frontend: Object.freeze({
|
|
policyId: `${operationId}_V1`,
|
|
requestByteLimit: 0,
|
|
responseByteLimit,
|
|
totalDeadlineMs: 10_000,
|
|
retryBudget: 2 as const,
|
|
authProfileId: "ANONYMOUS",
|
|
diagnosticsOperation: `techLog.public.${operationId}`,
|
|
}),
|
|
}) as InstalledHttpContract<unknown, unknown, unknown>;
|
|
}
|
|
|
|
const bySlug = (input: never) => {
|
|
const value = input as unknown as Readonly<{ slug: string }>;
|
|
return Object.freeze({
|
|
pathValues: Object.freeze({ slug: value.slug }),
|
|
queryEntries: NO_QUERY,
|
|
});
|
|
};
|
|
|
|
const P = "/api/v1/public";
|
|
|
|
const HTTP_CONTRACTS = Object.freeze([
|
|
publicRead("getPublicSite", `${P}/site`, 32_768),
|
|
publicRead("getPublicHome", `${P}/home`, 262_144),
|
|
publicRead("exploreKnowledge", `${P}/explore/knowledge`, 262_144, (input: never) => {
|
|
const value = input as unknown as Readonly<{
|
|
type?: string;
|
|
topic?: string;
|
|
project?: string;
|
|
page?: number;
|
|
size?: number;
|
|
}>;
|
|
return Object.freeze({ pathValues: NO_PATH, queryEntries: queryOf(value ?? {}) });
|
|
}),
|
|
publicRead("exploreQuestions", `${P}/explore/questions`, 262_144, (input: never) => {
|
|
const value = input as unknown as Readonly<{
|
|
status?: string;
|
|
topic?: string;
|
|
project?: string;
|
|
page?: number;
|
|
size?: number;
|
|
}>;
|
|
return Object.freeze({ pathValues: NO_PATH, queryEntries: queryOf(value ?? {}) });
|
|
}),
|
|
publicRead("listPublicTopics", `${P}/topics`, 65_536),
|
|
publicRead("getPublicTopic", `${P}/topics/{topicSlug}`, 262_144, (input: never) => {
|
|
const value = input as unknown as Readonly<{ topicSlug: string }>;
|
|
return Object.freeze({
|
|
pathValues: Object.freeze({ topicSlug: value.topicSlug }),
|
|
queryEntries: NO_QUERY,
|
|
});
|
|
}),
|
|
publicRead("getPublicCase", `${P}/cases/{slug}`, 524_288, bySlug),
|
|
publicRead("getPublicReference", `${P}/references/{slug}`, 524_288, bySlug),
|
|
publicRead("getPublicQuestion", `${P}/questions/{slug}`, 524_288, bySlug),
|
|
publicRead("getPublicConcept", `${P}/concepts/{slug}`, 524_288, bySlug),
|
|
publicRead("listPublicProjects", `${P}/projects`, 262_144),
|
|
publicRead("getPublicProject", `${P}/projects/{slug}`, 262_144, bySlug),
|
|
publicRead("listPublicProjectDecisions", `${P}/projects/{slug}/decisions`, 262_144, bySlug),
|
|
publicRead("listPublicProjectRecords", `${P}/projects/{slug}/records`, 262_144, bySlug),
|
|
publicRead("listPublicProjectActivities", `${P}/projects/{slug}/activities`, 262_144, bySlug),
|
|
publicRead("listPublicReleases", `${P}/releases`, 262_144),
|
|
publicRead("getPublicRelease", `${P}/releases/{version}`, 262_144, (input: never) => {
|
|
const value = input as unknown as Readonly<{ version: string }>;
|
|
return Object.freeze({
|
|
pathValues: Object.freeze({ version: value.version }),
|
|
queryEntries: NO_QUERY,
|
|
});
|
|
}),
|
|
publicRead("getPublicProfile", `${P}/profile`, 65_536),
|
|
publicRead("searchPublicResources", `${P}/search`, 262_144, (input: never) => {
|
|
const value = input as unknown as Readonly<{ q?: string; page?: number; size?: number }>;
|
|
return Object.freeze({ pathValues: NO_PATH, queryEntries: queryOf(value ?? {}) });
|
|
}),
|
|
]);
|
|
|
|
export const TECH_LOG_PUBLIC_OPERATION_IDS = Object.freeze(
|
|
HTTP_CONTRACTS.map((entry) => entry.contract.operationId),
|
|
);
|
|
|
|
export type TechLogPublicOperationId =
|
|
(typeof TECH_LOG_PUBLIC_OPERATION_IDS)[number];
|
|
|
|
export const TECH_LOG_PUBLIC_CONTRIBUTION: InstalledContractContribution =
|
|
Object.freeze({
|
|
contributionId: "tech-log-public-http-v1",
|
|
featureId: TECH_LOG_FEATURE_ID,
|
|
source: Object.freeze({
|
|
kind: "EXTERNAL_PACKAGE" as const,
|
|
package: Object.freeze({
|
|
packageId: canonicalSource.packageId,
|
|
version: canonicalSource.version,
|
|
digest: canonicalSource.digest as `sha256:${string}`,
|
|
runtimeProtocolVersion: 1 as const,
|
|
sourceRevision: canonicalSource.sourceRevision,
|
|
}),
|
|
}),
|
|
http: HTTP_CONTRACTS,
|
|
events: Object.freeze([]),
|
|
});
|