커스텀 도메인
호스트네임 카테고리의 API 작업 4개를 다룹니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames | 프로젝트에 연결된 도메인 목록 (runlot domain list) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames | 커스텀 도메인을 연결합니다 (runlot domain add) |
| DELETE | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host} | 커스텀 도메인 연결을 해제합니다 (runlot domain rm) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}/verify | 지금 도메인을 검증합니다 (runlot domain verify) |
GET /v1/orgs/{orgSlug}/projects/{projectName}/hostnames
기본 호스트네임(kind: default)과 커스텀 도메인(kind: custom)이 함께 반환됩니다. 커스텀 도메인 레코드에는 안내 레코드(verify)와 상태가 포함됩니다(docs/domains.md §3.2). viewer 이상의 권한이 필요합니다.
operationId listHostnames
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 목록 조회 | HostnameList |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/hostnames
이름은 소문자 punycode로 정규화되어 저장됩니다. 와일드카드 아래의 이름과 우리 도메인(*.runlot.app, *.runlot.dev, *.runlot.io, 앱 도메인) 아래의 이름은 허용되지 않습니다.
레코드는 pending_dns 상태로 생성되며, 그 순간부터 해당 이름을 예약합니다. 검증이 진행되는 동안에는 다른 프로젝트가 같은 이름을 사용할 수 없습니다. 연결되기 전까지는 라우팅에 추가되지 않으므로, 해당 이름으로의 요청은 404 unknown_hostname을 반환합니다.
같은 프로젝트가 같은 이름을 다시 보내면, 기존 행이 변경 없이 그대로 반환됩니다(멱등). 토큰이 바뀌면 이미 설정된 TXT 레코드가 즉시 잘못된 값이 되기 때문입니다. member 이상의 권한이 필요합니다. hostname.add로 감사 기록됩니다.
operationId addHostname
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 새로 생성된 레코드 또는 기존 레코드 | Hostname |
| 400 | 유효한 이름 형식이 아니거나(bad_request), 와일드카드이거나, 자체 도메인 아래에 있는 경우 | Error |
| 403 | — | — |
| 404 | — | — |
| 409 | 다른 프로젝트가 이미 사용 중인 이름입니다. code는 hostname_taken입니다. | Error |
DELETE /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}
Cloudflare 커스텀 호스트네임과 Runlot DNS 존의 관리 레코드를 함께 삭제합니다. 기본 호스트네임은 삭제할 수 없습니다(400). 배포가 주소를 결정하므로, 여기서 삭제하면 다음 배포 전까지 프로젝트에 접근할 수 없게 됩니다. member 이상의 권한이 필요합니다. hostname.delete로 감사됩니다.
operationId deleteHostname
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 204 | 분리됨 | — |
| 400 | 기본 호스트네임입니다 | Error |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}/verify
백그라운드 작업(1분 주기)과 동일한 검증 절차를 즉시 실행합니다. 소유권 검증은 다음 세 조건 중 하나를 충족하면 통과합니다: 이름이 자체 존 안에 있고 org가 일치하는 경우, _runlot-verify.<host> TXT 레코드가 일치하는 경우, 또는 <host>의 CNAME이 폴백 오리진을 가리키는 경우입니다.
소유권 증명 없이는 active 상태가 될 수 없습니다. 통과하지 못하면 상태는 그대로 유지되며, lastError에 현재 관측된 내용이 담깁니다. member 이상의 권한이 필요합니다.
operationId verifyHostname
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 확인 후의 행 | Hostname |
| 403 | — | — |
| 404 | — | — |