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

제한형 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는 리버스 프록시에서 종료하세요.

관련 문서