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

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(요청: HttpRequest) -> HttpResponse {
  if 요청.method == "GET" && 요청.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는 리버스 프록시에서 종료하세요.

관련 문서