Files
tech-log-frontend/src/features/tech-log/contracts/tech-log-public-contract-contribution.ts
T
DongHyeonkaandClaude Opus 5 8996430d23 fix: 공개 개념 문서를 열 수 있게 한다
`/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
2026-09-01 14:37:39 +09:00

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([]),
});