서버 유틸리티 개요

srvkit 폴더는 service, signal, server job이 사용하는 서버 전용 로직을 담습니다. 재사용 가능한 서버 추상화를 이곳에 두면 convention 파일은 비즈니스 동작에만 집중할 수 있습니다.

외부 라이브러리를 감싸는 안전한 위치이기도 합니다. *.service.ts 같은 주요 convention 파일은 임의의 외부 import를 엄격하게 제한하므로, vendor SDK나 낮은 수준의 서버 API는 보통 srvkit을 한 번 거쳐서 사용합니다.

srvkit/ 에 두는 것

Guard

mutation 실행 전에 계정 role을 확인하는 것처럼 signal에서 사용하는 요청 방어 로직입니다.

InternalArg

account, self, admin identity처럼 request context에서 읽어 signal 실행 인자로 주입하는 값입니다.

Middleware와 WebProxy

app logic 실행 전에 server context를 붙이거나 redirect, rewrite, header 추가를 처리하는 request pipeline 확장입니다.

서버 helper

hash, encryption, file handling, image inspection, token utility 같은 재사용 서버 로직입니다.

Adaptor

storage, email, payment, vendor API 같은 외부 시스템을 service dependency로 감싸는 구조입니다.

Class utility

로직 추상화를 위한 객체나 SDK client처럼 option을 통해 service에 주입되는 서버 전용 class입니다.

서버 레벨 적용

서버 레벨 적용사항은 app 또는 library option chain에 한 번 등록합니다. WebProxy는 라우팅 전에 웹 요청을 바꾸고, Middleware는 signal endpoint 로직이 실행되기 전에 request context를 준비합니다.

WebProxy는 page가 선택되기 전에 웹 라우팅을 처리합니다.

Middleware

Middleware는 signal 요청 주변에서 실행되며, 비즈니스 로직이 실행되기 전에 서버가 만든 값을 request context에 붙일 수 있습니다.

srvkit/middlewares.ts

WebProxy

WebProxy는 웹 요청이 page에 도달하기 전에 실행됩니다. routing과 rendering을 위해 redirect, rewrite, request header 변경이 필요할 때 사용합니다.

srvkit/webProxies.ts

Apply Them In Options

srvkit에 선언한 뒤에는 app 또는 library option chain에서 middleware와 web proxy를 등록합니다.

lib/option.ts

Signal 레벨 적용

Signal 레벨 적용사항은 signal endpoint 또는 slice 단위로 적용합니다. Guard는 endpoint 실행 가능 여부를 판단하고, InternalArg는 신뢰할 수 있는 서버 context를 exec 인자로 바꿉니다.

서버 레벨 Middleware가 context를 준비한 뒤, signal 레벨 적용사항이 각 endpoint를 제어합니다.

Guard

Guard는 요청이 signal을 실행해도 되는지 확인합니다. 인증, role 확인, 소유권 확인, 서버 측 요청 방어에 사용합니다.

srvkit/guards.ts

order.signal.ts

InternalArg

InternalArg는 request 또는 websocket context를 읽어 서버가 만든 값을 signal exec 인자로 추가합니다. 클라이언트에게 보내라고 요구하지 않고 context 데이터가 필요한 비즈니스 로직에 사용합니다.

srvkit/internalArgs.ts

signal exec shape

서비스 로직과 외부 라이브러리

service 코드가 crypto, AI SDK, HTTP client, 기타 서버 전용 패키지를 필요로 한다면 먼저 srvkit에서 감싸세요. 순수 helper는 service에서 바로 import할 수 있지만, use<T>()로 사용하는 class instance는 먼저 option chain에서 제공해야 합니다.

srvkit/createHash.ts

srvkit/EmailClient.ts

option.ts

order.service.ts

Adaptor와 plug

Adaptor는 외부 시스템을 service dependency로 사용할 수 있게 만듭니다. srvkit에 작은 adaptor를 선언하고, 필요한 service에서 plug해서 사용합니다. 순환 의존성만 만들지 않는다면 adaptor끼리도 서로 plug할 수 있습니다.

srvkit/paymentApi.ts

order.service.ts

실전 규칙

service나 signal이 복잡해질 서버 전용 helper 코드는 srvkit에 둡니다.

외부 라이브러리는 convention 파일에 직접 넣기 전에 srvkit에서 먼저 감싸 사용합니다.

요청 방어에는 Guard를, context에서 만든 signal 인자에는 InternalArg를 사용합니다.

service가 재사용 가능한 외부 시스템 dependency를 필요로 하면 adapt와 plug를 사용합니다.

앱 전용 연동은 app srvkit에, 재사용 가능한 연동은 library srvkit에 둡니다.