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

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

관련 문서