Topazdocs
애플리케이션 만들기

제한형 HTTP 서비스

명시적인 한계를 가진 검사된 Topaz HTTP/1.1 서비스를 빌드하고 실행·배포합니다.

http-service 대상은 검사된 Topaz 요청 처리기 하나를 관리형 네이티브 HTTP/1.1 서비스로 만듭니다. 생성된 호스트가 리스너, HTTP 프레이밍, 데드라인, 과부하 응답, 로그와 종료 절차를 맡습니다. Topaz 코드는 HttpRequest를 받고 HttpResponse를 반환합니다.

이는 범위가 명확한 서비스 호스트이지 범용 웹 프레임워크가 아닙니다. 아웃바운드 네트워크, 소켓, TLS, HTTP/2, WebSocket, 세션, 공유 가변 애플리케이션 상태, 주변 환경 변수 접근, async/await 문법을 추가하지 않습니다. 공개 TLS나 인터넷 경계 정책이 필요하면 생성된 프로세스 앞에 일반적인 리버스 프록시를 둡니다.

패키지 생성과 검사

BASH
topaz init --target http-service --root hello-service
topaz fmt --root hello-service --check
topaz check --root hello-service
topaz test --root hello-service

엔트리는 다음과 같은 구체적인 처리기 하나를 정확히 export해야 합니다.

TOPAZ
import std.http { HttpRequest, HttpResponse, text }

export function handle(req: HttpRequest) -> HttpResponse {
  if req.method == "GET" && req.url.path() == "/health" {
    return text(200, "ok")
  }
  text(404, "not found")
}

handle이 없거나 제네릭·가변 인자·기본 인자 함수이거나 요청 또는 응답 타입이 다르면 리스너를 열기 전에 검사가 실패합니다.

실제 루프백 HTTP로 개발

BASH
topaz dev --root hello-service --port 8080
curl --fail-with-body http://127.0.0.1:8080/health

topaz dev는 바인드 주소를 항상 127.0.0.1로 덮어씁니다. 배포 때와 같은 관리형 서비스 실행 파일을 만들고 인터럽트를 그 프로세스에 전달하므로 Ctrl-C도 실제 종료 경로를 실행합니다.

유한한 예산 설정

[service]는 알 수 없는 키와 허용 범위를 벗어난 값을 거부합니다. 다음 기본값은 생성 제품 계약의 일부입니다.

TOML
[service]
bind = "127.0.0.1"
port = 8080
workers = 1
max_connections = 64
queue_capacity = 32
max_target_bytes = 8192
max_header_bytes = 16384
max_headers = 64
max_body_bytes = 1048576
header_timeout_ms = 5000
body_timeout_ms = 5000
handler_timeout_ms = 1000
shutdown_grace_ms = 5000
log_format = "text"

workers는 단일 스레드 리액터에서 동시에 실행할 수 있는 처리기의 상한입니다. 요청마다 새로운 런타임 컨텍스트와 모듈 그래프를 만들며, 요청끼리 Topaz 힙을 공유하지 않습니다. 협력적 처리기가 시간 제한을 넘으면 실제 future를 폐기하고 용량을 다시 사용할 수 있습니다. 끝나지 않을 수 있는 생성 코드의 루프에는 취소 체크포인트가 들어가며, 동기식 단일 연산의 작업량은 허용한 입력 크기로 제한합니다.

실행 파일은 같은 설정을 케밥 표기 플래그로 받습니다. 매니페스트에는 루프백 IP만 쓸 수 있습니다. 빌드된 서비스를 다른 IP에 바인드하려면 프로세스 인자로 명시해야 합니다.

BASH
./target/release/program --bind 0.0.0.0 --port 8080

리스너를 열지 않고 명령행 재정의까지 반영된 최종 설정을 검사할 수 있습니다.

BASH
./target/release/program --port 9090 --workers 2 --print-config

이 명령은 topaz.httpServiceConfig.v1 JSON 객체 하나를 출력합니다. 관리형 topaz-service-config.json은 같은 스키마로 내장 기본값을 기록하고, --print-config는 검증된 실행 시점 유효값을 표시합니다. 알 수 없거나 중복되고 형식 또는 범위가 잘못된 옵션은 바인드 전에 실패합니다.

제품 빌드와 복사

BASH
topaz build --root hello-service --locked --release --out-dir hello-service-product
cp -R hello-service-product /srv/hello-service
cd /srv/hello-service
./target/release/program --help
./target/release/program

관리 디렉터리에는 네이티브 실행 파일, topaz-service-config.json, 제3자 고지, Topaz 라이선스와 고지, topaz-artifact.json이 들어 있습니다. 실행 시에는 패키지 소스, Topaz 체크아웃, Cargo 레지스트리, 임시 빌드 작업공간이 필요하지 않습니다. 무결성 메타데이터와 고지가 실행 파일과 함께 남도록 디렉터리 전체를 복사하세요.

실패와 관측

  • 본문이 너무 크면 413, 요청 대상이 너무 길면 414, 헤더 집합이 너무 크면 HTTP 응답을 만들 수 있는 경우 431을 반환합니다.
  • 처리기 대기열이 가득 차면 Connection: close와 함께 503을 반환합니다.
  • 처리기 데드라인을 넘으면 일반화된 504를 반환하고 worker 용량을 돌려놓습니다.
  • 런타임 fault나 잘못된 응답은 소스 경로, 요청 본문, 헤더 값, Topaz fault 메시지를 노출하지 않고 일반화된 500으로 바뀝니다.
  • 응답에는 x-topaz-request-id가 있습니다. 텍스트 또는 topaz.httpServiceLog.v1 JSON 호스트 로그에는 같은 요청 ID, 제한된 코드, 상태나 로컬 진단만 기록하며 요청 대상·본문·헤더 값은 기록하지 않습니다.
  • 로그는 service-started, shutdown-requested, shutdown-complete, shutdown-forced를 구분합니다. log_format = "off"는 서비스 로그를 끄지만 명시적인 --print-config 출력은 유지합니다.
  • SIGINT와 Unix의 SIGTERM은 새 연결 수락을 멈추고 shutdown_grace_ms 동안 기존 연결을 정리한 뒤 정상 또는 강제 종료를 기록합니다.

호스트는 상태 코드와 헤더 문법을 검사하고 Content-Length, 전송 인코딩, hop-by-hop 헤더를 소유합니다. 애플리케이션 응답은 이러한 전송 필드를 덮어쓸 수 없습니다.

배포 경계

실행 파일은 프로세스 감독기 아래에서 실행하세요. TLS와 최신 HTTP 프로토콜은 리버스 프록시에서 종료하고, 평문 HTTP/1.1을 설정한 서비스 주소로 전달하며, 생성된 본문·헤더·데드라인 한계를 유지합니다. /health는 Topaz 처리기가 실제로 구현한 준비 상태 의미로만 사용합니다. 복사해 둔 이전 공개 마이너 산출물이 롤백 단위이며, 설정 변경은 관리 산출물의 바이트를 다시 쓰지 않습니다.