토파즈문서
애플리케이션 만들기

제한형 HTTP 서비스

검사된 HTTP/1.1 핸들러 하나를 제한형 생성 서비스 호스트 안에서 빌드하고 점검해 배포합니다.

검사된 토파즈 함수 하나가 HttpRequest를 받아 HttpResponse를 반환해야 할 때 http-service를 선택합니다. 생성된 네이티브 호스트가 리스너, HTTP/1.1 프레이밍, 유한한 요청 예산, 과부하 응답, 로그와 종료를 담당합니다.

이는 범용 Web 서버 프레임워크가 아닙니다. 아웃바운드 네트워크, Raw 소켓, 주변 환경 접근, 공유 가변 토파즈 상태, TLS, HTTP/2, WebSocket이나 세션을 부여하지 않습니다. 공개 TLS와 인터넷 경계 정책은 프로세스 앞의 일반적인 리버스 프록시에서 처리하세요. 이 명시적인 Capability 경계는 제품 설계의 일부입니다.

먼저 첫 애플리케이션을 완료하세요. 서비스 빌드에는 배포 플랫폼용 Rust 도구 모음이 필요합니다.

생성, 잠금, 테스트

스캐폴드는 패키지 매니페스트, 제한형 서비스 기본값과 구체적인 핸들러를 제공합니다.

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

진입 모듈은 다음 모양의 핸들러 하나만 내보냅니다.

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")
}

핸들러가 없거나 제네릭, 가변 인자, 기본 인자를 사용하거나 타입이 다르면 리스너를 시작하기 전에 검사기가 거부합니다.

루프백에서 개발하기

실제 생성 서비스를 루프백에서 실행하고 상태 확인 경로를 요청합니다.

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로 고정하고 관리형 서비스를 다시 빌드하며 중단 신호를 전달합니다. 8080 포트를 이미 사용 중이면 --port로 다른 루프백 포트를 고르세요.

유한한 서비스 예산 유지하기

스캐폴드는 [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"

알 수 없는 키와 범위를 벗어난 값은 패키지를 읽는 동안 실패합니다. 각 요청은 새 런타임 문맥과 모듈 그래프를 사용하므로 요청끼리 토파즈 힙을 공유하지 않습니다. 대기열 포화, 지나치게 큰 입력, 핸들러 마감 시간과 잘못된 응답은 무제한 작업이 아니라 제한된 호스트 결과가 됩니다.

제품 빌드와 점검

BASH
topaz build --root hello-service --locked --release --out-dir hello-service-product
cd hello-service-product
./target/release/program --print-config
./target/release/program

Windows에서는 target\release\program.exe를 실행합니다. 제품 구조는 다음과 같습니다.

출력
hello-service-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── THIRD-PARTY-NOTICES.txt
├── target
│   └── release
│       └── program[.exe]
├── topaz-artifact.json
└── topaz-service-config.json

program[.exe]는 Unix의 program과 Windows의 program.exe를 함께 나타냅니다. --print-config는 리스너를 열지 않고 유효 설정을 검증해 출력합니다. 관리형 JSON 파일은 내장 기본값을 기록합니다. 실행 시 덮어쓰기는 명시적 명령줄 옵션으로 전달하며, 루프백이 아닌 바인드는 다음과 같이 지정합니다.

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

의도한 네트워크 경계 뒤에서만 사용하세요. 매니페스트에는 루프백 주소만 쓸 수 있습니다.

관찰 가능한 실패

  • 지나치게 큰 본문, 대상이나 헤더 집합은 프레이밍이 허용하는 범위에서 제한된 HTTP 오류를 냅니다.
  • 핸들러 대기열이 차면 503, 핸들러가 마감 시간을 넘기면 504를 반환합니다.
  • 런타임 결함이나 잘못된 애플리케이션 응답은 소스 경로, 요청 내용, 토파즈 결함 문구를 노출하지 않는 일반 500이 됩니다.
  • 응답과 호스트 로그는 같은 요청 ID를 사용합니다. 로그에는 대상, 본문과 헤더 값이 들어가지 않습니다.
  • SIGINT와 Unix의 SIGTERM은 새 요청을 막고 shutdown_grace_ms까지 기존 작업을 비웁니다.

check나 test가 실패하면 토파즈 진단을 고친 뒤 같은 명령을 반복하세요. 빌드 출력 디렉터리에서 변경된 관리 파일이나 다른 대상을 발견하면 기존 디렉터리를 조사용으로 보존하고 새 빈 --out-dir을 고릅니다.

소스 없는 배포

실행 파일, 설정 기록, 무결성 매니페스트, 라이선스와 고지가 함께 있도록 hello-service-product/ 전체를 복사하세요. 복사한 제품에는 패키지 소스, 토파즈 CLI, 레지스트리나 임시 Cargo 작업공간이 필요하지 않습니다. 프로세스 관리자 아래에서 실행하고 생성된 예산을 유지하며 공개 TLS는 리버스 프록시에서 종료하세요.

관련 문서