서비스 간 인증 라이브러리와 포털↔HAL 작업 계약 문서

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-26 11:05:43 +00:00
parent 8607f19e62
commit 5cf7799b51
2 changed files with 90 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 포털 ↔ HAL 작업 계약(HAL-JOBS)
+
+포털 어댑터 `portal/hal/client.mjs`(deps.hal) 와 HAL `/portal/v1/*` 가 공유하는 계약. 인증은 lib/serviceauth(키 id `portal`).
+
+## deps.hal (포털 쪽 인터페이스)
+
+```js
+hal.createJob({ kind, target, payload, idempotencyKey, groupId, subjectType, subjectId }) → { halJobId, status }
+hal.getJob(halJobId) → { id, kind, status(lib/status JOB_STATUS 코드), steps:[{id,title,state,detail}], progress, result, error, errorCode, updatedAt, children? }
+hal.cancelJob(halJobId) / hal.retryJob(halJobId) / hal.revertJob(halJobId) / hal.resumeJob(halJobId)
+hal.listServers({ role }) → [{ id, name, role:'web'|'mail'|'backup'|'control', location, status:'ready'|'maintenance'|'isolated'|'offline', acceptsNew, health, lastSeenAt, capacity:{ diskFreeBytes, diskTotalBytes, memFreeBytes, cpuLoad, sitesHosted, reservedBytes }, version:{ agent, modules:{} } }]
+hal.pickServer({ role:'web', needBytes }) → { serverId } | null   // 신규 배치 허용·여유 있는 서버
+hal.issueExternalAgentToken({ groupId, siteId, label }) → { agentId, token(1회), expiresAt, installCommand }
+hal.getExternalAgent(agentId) → { id, status:'pending'|'connected'|'offline'|'revoked', lastSeenAt, version, lastDeploy:{...} }
+hal.revokeExternalAgent(agentId)
+hal.health() → { ok, version, uptime }   // 실패 시 code 'service_unreachable'
+```
+
+HAL 이 응답하지 않으면 어댑터는 `service_unreachable` 을 던지고 호출자는 `정보 확인 지연` 을 표시하며 신규 증가를 허용하지 않는다.
+HAL 은 작업 상태 변화를 포털 `POST /internal/hal-events` (키 id `hal`) 로 민다: `{ halJobId, status, steps, result, error, updatedAt }`. 포털은 5초 주기 조회로도 맞춘다.
+
+## 작업 종류와 payload (target = 관리 서버 id 또는 외부 Agent id)
+
+| kind | payload | result |
+|---|---|---|
+| `site.deploy` | `{ siteId, versionRef, bundleUrl(포털이 Webmaker 저장본을 tar.gz 로 내놓는 서명 URL) 또는 bundleFromWebmaker:{projectId, versionRef}, runtime:'static'|'node', env:{}, domains:[...], primaryDomain, previousVersion, external:bool }` | `{ version, deployedAt, internalCheck:{ok,status,ms}, externalCheck:{ok,url,status}, siteUrl, leftovers:[] }` |
+| `site.rollback` | `{ siteId, toVersion }` | `{ version }` |
+| `site.remove` | `{ siteId, keepData:bool }` | `{ removed:true, leftovers:[] }` |
+| `site.check` | `{ siteId, urls:[...], expectMarker }` | `{ checks:[{url,status,ok,ms,tls:{valid,expiresAt}}] }` |
+| `site.usage` | `{ siteIds:[...] }` | `{ sites:{ [siteId]: { diskBytes, dbBytes, uploadsBytes, outBytesDay, outBytesMonth, outBytesTotal, inBytesDay, inBytesMonth, inBytesTotal, req24h, pv24h, series7d:[...], series30d:[...], errorRate, p95ms, measuredAt } } }` |
+| `domain.vhost` | `{ siteId, domains:[...], primaryDomain, redirectOld:bool, maintenance:bool }` | `{ applied:[...], certs:{domain:{state,expiresAt}} }` |
+| `domain.cert` | `{ siteId, domains:[...], email }` | `{ issued:[...], failed:[{domain,reason}], expiresAt }` |
+| `domain.probe` | `{ name, expectA:[...], expectTxt:{name,value}? }` | `{ a:[...], txtOk, resolvedAt }` |
+| `backup.create` | `{ siteId, scope:{files,db,uploads,config}, storeServerId, retentionTag }` | `{ backupId, location, sizeBytes, checksum, verified:true, createdAt }` |
+| `backup.verify` | `{ location, checksum }` | `{ ok }` |
+| `backup.restore` | `{ siteId, location, checksum, protectPoint:true, isolatedVerify:true }` | `{ protectPointLocation, restoredVersion, externalCheck }` |
+| `backup.delete` | `{ location }` | `{ deleted }` |
+| `site.relocate` | `{ siteId, fromServerId, toServerId, kind:'static'|'dynamic', writeFreeze:bool, domains, primaryDomain }` | 단계: precheck → prepare → precopy → verify_copy → final_sync → verify_new → switch → external_check → cleanup → done. result `{ newServerId, switchedAt, oldRetainedUntil }` |
+| `module.deploy` / `module.update` / `module.rollback` / `module.health` | HAL 내부(운영자 콘솔) | 대상별 자식 작업 |
+
+External Pull Agent(외부 서버)는 `site.deploy`·`site.remove`·`site.check` 만 받는다.