Files
DongHyeonka 6c5818faec refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.

고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
  V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
  새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
  JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
  하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
  그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
  해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
  "REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
  src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).

버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
  바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
  매핑을 알아야 한다. 프로필 항목 하나가 더 작다.

위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
  않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
  그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
  보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
  behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
  작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
  항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
  청크라 초기 크기에 영향이 없다.

검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
  undefined to match object { transport: 'BEARER_HEADER', …(1) }",
  "expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
  (FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
  207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
  http-scenario-evidence, ci-workflow-generation, lab-performance,
  fixture-node-modules, deployment-admission, security-followup-archive).
  tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
2026-11-03 00:55:33 +09:00

242 lines
7.4 KiB
TypeScript

import {
defineBrowserRpcOperation,
defineBrowserRpcProviderProfile,
defineBrowserRpcRequestEncoder,
type BrowserRpcOperationV3,
type BrowserRpcProviderProfile,
} from "../../../src/contracts/browser-rpc.ts";
import {
mappingSuccess,
type InstalledBoundaryMapper,
} from "../../../src/contracts/boundary-mapper.ts";
import type { RuntimeSchemaCodec } from "../../../src/contracts/schema-registry.ts";
export const DESCRIPTOR_DIGEST = "a".repeat(64);
export const RUNTIME_DIGEST = "b".repeat(64);
export type ResourceView = Readonly<{ id: string; label: string }>;
export function unaryProfile(
overrides: Partial<BrowserRpcProviderProfile> = {},
): BrowserRpcProviderProfile {
return defineBrowserRpcProviderProfile({
runtimeProfileId: "CONNECT_REFERENCE_UNARY",
providerId: "REFERENCE_RPC",
fixedBaseUrl: "https://rpc.example.test/base/",
runtimeId: "connect-es-web",
runtimeVersion: "2.1.0",
runtimeDigest: RUNTIME_DIGEST,
protocol: "CONNECT_HTTP",
runtimeKind: "CONNECT_WEB_FETCH",
clientApiKind: "PROMISE_UNARY",
rpcKind: "UNARY",
messageEncoding: "PROTO",
framing: "CONNECT_BARE",
requestMethod: "POST",
descriptorArtifactId: "buf.example.resource.v1",
descriptorDigest: DESCRIPTOR_DIGEST,
allowedProcedures: ["example.resource.v1.ResourceService/GetResource"],
authProfileId: "EXTERNAL_BEARER",
csrfProfileId: "NO_CSRF_BEARER",
corsProfileId: "SAME_ORIGIN_RPC",
errorProfileId: "CONNECT_ERROR_V1",
deadlineProfileId: "RPC_TOTAL_5S",
retryProfileId: "RPC_RETRY_NONE",
retryOwner: "NONE",
maxAttempts: 1,
backoffMs: [],
retryableFailures: [],
maxRetryAfterMs: 0,
deadlineDialect: "CONNECT_TIMEOUT_MS",
cancelDialect: "ABORT_SIGNAL",
rawByteCeilingOwner: "EDGE_AND_TRANSPORT",
streamMessageCompression: "IDENTITY_ONLY",
...overrides,
});
}
export function unaryOperation(
overrides: Partial<BrowserRpcOperationV3> = {},
): BrowserRpcOperationV3 {
return defineBrowserRpcOperation({
contractVersion: 3,
operationId: "GET_RPC_RESOURCE",
owner: "feature-browser-rpc-test",
protocol: "CONNECT_HTTP",
semantics: "QUERY",
replayPolicy: "SAFE",
idempotencyKeyPolicy: "NONE",
idempotencyLevel: "IDEMPOTENT",
dataClassification: "INTERNAL",
runtimeProfileId: "CONNECT_REFERENCE_UNARY",
providerId: "REFERENCE_RPC",
fullyQualifiedService: "example.resource.v1.ResourceService",
method: "GetResource",
rpcKind: "UNARY",
requestMessageId: "example.resource.v1.GetResourceRequest",
responseMessageId: "example.resource.v1.Resource",
descriptorArtifactId: "buf.example.resource.v1",
descriptorDigest: DESCRIPTOR_DIGEST,
requestSchemaId: "RpcResourceRequest",
responseSchemaId: "RpcResourceResponse",
requestEncoderId: "RpcResourceRequestEncoder",
mapperId: "RpcResourceMapper",
authProfileId: "EXTERNAL_BEARER",
csrfProfileId: "NO_CSRF_BEARER",
errorProfileId: "CONNECT_ERROR_V1",
deadlineProfileId: "RPC_TOTAL_5S",
retryProfileId: "RPC_RETRY_NONE",
serverStateProfileId: "RpcResourceQuery",
maxRequestMessageBytes: 1_024,
maxResponseMessageBytes: 4_096,
maxResponseMessages: 1,
maxTotalResponseBytes: 4_096,
maxBufferedBytes: 4_096,
idleDeadlineMs: null,
totalDeadlineMs: 5_000,
...overrides,
});
}
export function streamProfile(
overrides: Partial<BrowserRpcProviderProfile> = {},
): BrowserRpcProviderProfile {
return defineBrowserRpcProviderProfile({
...unaryProfile(),
runtimeProfileId: "CONNECT_REFERENCE_STREAM",
clientApiKind: "ASYNC_ITERABLE",
rpcKind: "SERVER_STREAM",
framing: "CONNECT_ENVELOPE",
allowedProcedures: [
"example.resource.v1.ResourceService/WatchResources",
],
retryProfileId: "RPC_STREAM_RETRY_NONE",
...overrides,
});
}
export function streamOperation(
overrides: Partial<BrowserRpcOperationV3> = {},
): BrowserRpcOperationV3 {
return defineBrowserRpcOperation({
...unaryOperation(),
operationId: "WATCH_RPC_RESOURCES",
semantics: "SERVER_STREAM",
runtimeProfileId: "CONNECT_REFERENCE_STREAM",
method: "WatchResources",
rpcKind: "SERVER_STREAM",
requestEncoderId: "RpcResourceStreamRequestEncoder",
retryProfileId: "RPC_STREAM_RETRY_NONE",
serverStateProfileId: null,
maxResponseMessages: 4,
maxTotalResponseBytes: 16_384,
maxBufferedBytes: 8_192,
idleDeadlineMs: 1_000,
totalDeadlineMs: 10_000,
...overrides,
});
}
export const SCHEMA_CODECS = Object.freeze({
RpcResourceRequest: Object.freeze({
schemaId: "RpcResourceRequest",
parse(value: unknown) {
if (
value &&
typeof value === "object" &&
typeof (value as { resourceId?: unknown }).resourceId === "string"
) {
return Object.freeze({
success: true,
data: Object.freeze({
resourceId: (value as { resourceId: string }).resourceId,
}),
});
}
return Object.freeze({
success: false,
issues: Object.freeze([
Object.freeze({ path: "resourceId", code: "INVALID_STRING" }),
]),
});
},
}),
RpcResourceResponse: Object.freeze({
schemaId: "RpcResourceResponse",
parse(value: unknown) {
if (
value &&
typeof value === "object" &&
typeof (value as { id?: unknown }).id === "string" &&
typeof (value as { name?: unknown }).name === "string"
) {
return Object.freeze({
success: true,
data: Object.freeze({
id: (value as { id: string }).id,
name: (value as { name: string }).name,
}),
});
}
return Object.freeze({
success: false,
issues: Object.freeze([
Object.freeze({ path: "", code: "INVALID_RESOURCE" }),
]),
});
},
}),
} satisfies Readonly<Record<string, RuntimeSchemaCodec>>);
export const MAPPERS = Object.freeze({
RpcResourceMapper: Object.freeze({
mapperId: "RpcResourceMapper",
mapperVersion: 1,
inputSchemaId: "RpcResourceResponse",
outputContractId: "ResourceView",
owner: "feature-browser-rpc-test",
maxOutputItems: 1,
map(input: unknown) {
const resource = input as Readonly<{ id: string; name: string }>;
return mappingSuccess<ResourceView>(
Object.freeze({ id: resource.id, label: resource.name }),
);
},
}),
} satisfies Readonly<Record<string, InstalledBoundaryMapper>>);
export const UNARY_ENCODER = defineBrowserRpcRequestEncoder({
encoderId: "RpcResourceRequestEncoder",
operationId: "GET_RPC_RESOURCE",
encode(value) {
const request = value as Readonly<{ resourceId: string }>;
return Object.freeze({
ok: true,
value: Object.freeze({ resourceId: request.resourceId }),
encodedBytes: request.resourceId.length,
});
},
});
export const STREAM_ENCODER = defineBrowserRpcRequestEncoder({
encoderId: "RpcResourceStreamRequestEncoder",
operationId: "WATCH_RPC_RESOURCES",
encode(value) {
const request = value as Readonly<{ resourceId: string }>;
return Object.freeze({
ok: true,
value: Object.freeze({ resourceId: request.resourceId }),
encodedBytes: request.resourceId.length,
});
},
});
export function isResourceView(value: unknown): value is ResourceView {
return (
!!value &&
typeof value === "object" &&
typeof (value as { id?: unknown }).id === "string" &&
typeof (value as { label?: unknown }).label === "string"
);
}