10/Documentation
Durable wire (실험적 기능)
개발자를 위한 Collie와 durable agent 간 통신 데이터 안내: 라우트, hello 및 에포크, ask의 수명 주기 및 요청 ID, 소켓과 토큰 전송, 제한 사항 및 버전 규칙을 다루며, 정확한 규칙은 WIRE.md 링크를 참조하십시오
실험적 기능입니다. 이후 마이너 릴리스에서 유선 프로토콜이 변경되거나 기능이 제거될 수 있습니다. 버전 및 상태를 알리는 헬로에서 변경 사항이 전달되는 방식을 설명합니다.
durable 유선 프로토콜은 Collie가 durable agent와 통신하는 방식입니다. 이 문서는 SDK 없이 durable agent를 작성하거나 SDK의 동작을 파악하려는 빌더를 위해 이를 설명합니다. 정확한 규칙은 WIRE.md에 있으며, 이 문서와 해당 파일의 내용이 일치하지 않는 경우 WIRE.md이(가) 우선합니다. durable SDK이(가) 이 모든 통신을 대신 처리합니다.
전송 대상
Collie가 전송을 시작하고 durable agent가 수신 대기하며, 모든 교환은 JSON 본문을 포함하는 하나의 HTTP 요청입니다.
durable agent는 비공개 Unix 소켓이나 URL(전송 계층)의 TLS 뒤에서 수신 대기합니다. Collie는 이를 폴링합니다. 푸시, WebSocket, 스트림은 없습니다. 모든 경로는 버전이 아닌 고정 이름인 /session/v1로 시작합니다. 첫 번째 hello를 제외한 모든 호출은 헤더 X-Collie-Session에 버전을 포함합니다. 요청 본문은 최대 64KiB의 단일 JSON 객체이며, 빈 POST 본문은 {}로 읽힙니다.
| 메서드 및 경로 | 동작 방식 | 응답 크기 제한 |
|---|---|---|
GET /hello | durable agent의 이름, 버전 범위, epoch, 준비 상태 및 caps | 16 KiB |
GET /snapshot | 레이아웃: 워크스페이스, 탭, 상태가 포함된 패널, 턴 및 미해결 ask, starter. ETag를 포함하며 변경 사항이 없으면 304로 응답합니다. | 4 MiB |
GET /pane/:id/events?after=N&epoch=E | 커서 이후의 패널 이벤트 | 8 MiB |
POST /pane/:id/answer | ask에 대한 응답 | 16 KiB |
POST /pane/:id/send | 패널용 텍스트. 실행 중인 턴을 유도하거나 다음 턴을 대기합니다. | 16 KiB |
POST /pane/:id/abort | 실행 중인 턴 중지 | 16 KiB |
POST /pane/:id/action | 패널의 벨트 버튼 중 하나 탭 | 16 KiB |
POST /rename | 워크스페이스 또는 탭의 새 제목 | 16 KiB |
POST /close | 패널, 탭 또는 워크스페이스 닫기 | 16 KiB |
POST /starter/:id | starter 실행. 응답에 새 패널 이름이 지정됩니다. | 16 KiB |
GET /conversations?after=C&limit=N | durable agent의 대화 목록(열린 대화 및 닫힌 대화, 최신순) | 1 MiB |
GET /conversation/:id/items?after=C&limit=N | 단일 대화의 항목(오래된 순) | 8 MiB |
POST /reopen | 닫힌 대화 다시 표시 | 16 KiB |
모든 오류는 409 stale 또는 404 no-such-pane와 같이 code을 포함하는 JSON 본문입니다. 다른 모든 경로는 404 not-found으로 응답합니다. 제한을 초과한 응답은 읽지 않으며, 응답이 중단된 POST의 결과는 알 수 없습니다(요청 ID).
Hello 및 epoch
hello은 durable agent가 누구인지 나타내고, epoch는 Collie가 해당 에이전트의 몇 번째 시작 인스턴스와 통신하고 있는지 나타냅니다.
hello 필드 | 포함된 내용 |
|---|---|
service | 정확히 collie-durable이어야 합니다. 이 값이 없으면 Collie는 durable agent를 다른 서버로 인식하고 더 이상 아무것도 호출하지 않습니다. |
protocol | durable agent가 지원하는 유선 버전 범위({ min, max }). 현재는 { min: 1, max: 1 }입니다. |
host.name | durable agent의 자체 이름. 표시용 텍스트 전용이며 최대 64바이트입니다. |
epoch | durable agent가 시작될 때마다 새로 무작위 생성되며, 최소 128비트이고 재사용되지 않습니다. |
ready | 시작 후 durable agent가 창을 배치하는 동안에는 false입니다. |
caps | durable agent가 수행할 수 있는 작업 목록이며 각각 불리언 값입니다. 누락된 cap은 false입니다. |
Collie는 먼저 버전 헤더 없이 hello을 호출하고, 양쪽이 모두 지원하는 가장 높은 버전을 선택한 뒤, 이후의 모든 호출에 해당 버전을 전송합니다. ready이 false인 동안에는 hello를 제외한 모든 경로가 503 starting으로 응답하며, 휴대폰에는 durable agent가 시작 중인 것으로 표시됩니다. durable agent는 모든 대화가 다시 표시되고 열려 있는 모든 ask가 다시 제기된 후에만 ready을 설정하므로, 재시작 시 배치가 불완전하게 표시되지 않습니다.
스냅샷의 ETag는 "<epoch>-<rev>"입니다. 읽는 이가 볼 수 있는 모든 변경 사항마다 rev이 증가하므로, 304 응답은 durable agent에 거의 부담을 주지 않습니다. 새 epoch는 durable agent가 재시작되었음을 Collie에 알립니다. Collie는 새 스냅샷을 읽을 때까지 기존 창을 계속 표시합니다. 그런 다음 이전 커서로 각 창을 읽고 한 번의 응답으로 창의 전체 현재 뷰를 가져옵니다.
정상 읽기 후 한 번 실패하면 해당 폴링에서는 마지막 스냅샷을 유지합니다. 연속으로 두 번 실패하면 durable agent를 연결할 수 없는 상태로 표시합니다. privacy walk에 실패한 소켓 경로는 즉시 연결 불가 상태가 됩니다.
Ask 및 답변
ask는 질문 카드이며, durable agent의 ask 이벤트부터 ask-closed까지 열려 있습니다.
| 상태 | 설정 주체 | 휴대폰에 표시되는 내용 |
|---|---|---|
| 열림 | durable agent가 ask를 제기합니다. ask가 열려 있는 동안 창에는 waiting이 표시됩니다. | "답변 필요" 아래에 표시되는 카드로, durable agent의 이름과 ask에 expiresAt이 있을 때 남은 시간이 함께 표시됩니다. |
| 변경됨 | durable agent가 ask를 즉석에서 변경하고 revision이 증가합니다. | 카드가 다시 그려집니다. 이전 양식을 탭하면 409 stale을 수신하며, 카드에는 "이 ask가 변경되었습니다. 다시 읽은 후 답변을 탭하십시오."라고 표시됩니다. |
| 수락됨 | 휴대폰이 응답하고 durable agent가 by: "phone"으로 ask를 닫습니다. | 카드가 사라지고, 옵션에 따라 도구가 실행되거나 거부됩니다. |
| durable agent에서 결정됨 | durable agent가 자체적으로 ask를 닫습니다(decidedBy: "program"). 턴 중단도 여기에 포함됩니다. | Chat에 표시되는 "durable agent에서 결정됨"으로 시작하는 줄이며, ask의 제목이 포함됩니다. |
| 시간 초과됨 | 시계가 expiresAt을 지납니다(decidedBy: "timeout"). | Chat에 표시되는 "답변 전 시간 초과됨"으로 시작하는 줄이며, ask의 제목이 포함됩니다. |
결정 후에 탭하면 첫 번째 결과와 함께 409 decided을 수신하며 아무것도 실행되지 않습니다. 그런 다음 카드에는 누가 먼저 결정했는지가 표시됩니다: "durable agent에서 결정됨.", "답변 전 시간 초과됨.", 또는 다시 탭한 후에는 "이미 답변했습니다. 이 카드는 다음 업데이트 시 사라집니다." durable agent가 더 이상 알지 못하는 ask는 200 too-late으로 응답합니다. 재시작 후 durable agent가 동일한 id로 해당 ask를 다시 제기할 수 있으므로, 카드에는 "수락되지 않았습니다. 질문이 곧 다시 표시될 수 있습니다."라고 표시됩니다.
| 규칙 | 이유 |
|---|---|
| ask id는 창 id와 도구 호출 id의 해시입니다. | 재시작 후 제기된 동일한 도구 호출은 동일한 id를 가지므로, 재시작 시점에 전송된 답변이 정상적으로 반영됩니다. |
permission 카드는 모델의 말이 아니라 도구의 이름과 인수로 구성됩니다. | 승인을 원하는 모델은 호출을 우호적으로 설명할 수 있습니다. |
TLS 뒤에 있는 durable agent는 allow-always을 제공하지 않아야 합니다. | 토큰이 유일한 관문이므로, 토큰을 보유한 사람의 응답 하나만으로 이후의 모든 호출이 통과될 수 있습니다. |
단어가 잘리거나 정제된 카드, 또는 도구 이름이 없는 카드에서는 휴대폰이 allow-always을(를) 제공하지 않습니다. | 사용자는 부여된 권한이 무엇을 포함하는지 볼 수 없습니다. |
expiresAt은(는) 시간대가 포함된 ISO 8601 형식입니다. | 해당 시점이 지나면 요청은 timeout에 의해 결정되며, 스냅샷에는 더 이상 미해결 상태로 표시되지 않습니다. |
| durable agent는 패널당 결정된 요청의 결과를 최소 최근 500개까지 유지합니다. | 뒤늦게 탭하면 일반 too-late 대신 decided과(와) 첫 번째 결과를 받습니다. |
요청은 permission, choice, text, form 중 하나입니다. 각각 고유한 응답 형태가 있으며 SDK의 질문 목록에 나열되어 있습니다.
요청 ID
휴대폰의 모든 동작에는 요청 ID가 있으므로 최대 한 번만 실행됩니다.
휴대폰은 의도당 하나의 요청 ID를 생성하고, Collie는 해당 ID를 전달하기 전에 자체 수신 확인을 기록합니다. durable agent는 해당 에포크의 ID를 최소 최근 500개까지 유지합니다. 완료된 ID가 반복되면 아무것도 실행하지 않고 replayed: true과(와) 함께 첫 번째 응답을 다시 받습니다. 다른 페이로드를 가진 동일한 ID는 409 request-id-reused을(를) 받습니다.
Collie는 자체적으로 POST를 재시도하지 않습니다. 시간 초과가 발생하거나 연결이 끊어지거나 5xx를 받는 POST는 결과를 알 수 없습니다. 답변의 경우 카드는 "Not sure the answer arrived. Try again sends it once more."라고 표시하며, 다시 시도하면 동일한 요청 ID를 보내므로 durable agent의 메모리가 반복 요청에 응답합니다.
요청이 닫혔거나 턴이 넘어간 것을 발견한 재시도는 첫 번째 시도가 성공했는지 알 수 없습니다. 그러면 Collie는 휴대폰에 "maybe applied"라고 응답하고, 카드는 "May already be applied. Check the chat."라고 표시하며, 해당 동작은 세 번 다시 전송되지 않습니다.
전송 계층
durable agent는 Collie 머신의 프라이빗 소켓 또는 토큰을 사용하는 TLS 중 하나의 전송 방식을 사용합니다.
경로, 본문, 버전 헤더, ETag, 오류 코드 등 두 방식 모두 바이트 단위로 동일합니다. durable agent에 접근할 수 있는 대상만 다릅니다.
| 소켓 경유 | 규칙 |
|---|---|
| 경로 | 절대 경로이며 최대 103바이트입니다. 양쪽 모두 COLLIE_DURABLE_SOCKET에서 이를 읽습니다. |
| 모드 | 소켓은 0600 모드이며, 0700 모드의 폴더에 있습니다. durable agent는 수신 대기하기 전에 오래된 소켓 파일을 제거합니다. |
| 경로 순회 | 각 연결 전에 Collie는 lstat을(를) 사용하여 경로의 모든 부분을 확인합니다. 심볼릭 링크인 부분은 없습니다. 소켓 폴더는 귀하의 소유이며 모드는 0700입니다. /tmp와(과) 같은 스티키 폴더를 제외하고는 상위 폴더 중 그룹이나 기타 사용자가 쓸 수 있는 폴더가 없습니다. 소켓은 귀하의 소유이며 그룹 또는 기타 권한이 없습니다. |
| 순회 실패 | Collie는 연결하지 않으며, socket-not-private 및 실패한 부분과 함께 durable agent를 도달 불가능으로 표시합니다. |
| 토큰 | 없음. 프라이빗 소켓이 게이트 역할을 합니다. |
| 동작을 수행할 수 있는 대상 | 귀하 사용자의 모든 프로세스입니다. durable agent는 403 caller-refused을(를) 반환하여 자체 하위 프로세스를 거부할 수 있습니다. |
| 시간 초과 | hello, snapshot, events의 경우 1000ms입니다. answer, send, stop, action, rename, close의 경우 3000ms입니다. starter의 경우 30000ms입니다. |
| Collie의 요청 빈도 | 휴대폰이 감시 중일 때는 1초마다, 그렇지 않으면 3초마다 폴링합니다. 중단된 durable agent는 폴링당 한 번씩 요청을 받습니다. |
| 지원 시스템 | Linux 및 macOS. Windows에는 소켓 전송 방식이 없습니다. |
| TLS 사용 | 규칙 |
|---|---|
| URL | https://, 또는 로컬 테스트용 http://127.0.0.1:<port> 혹은 http://localhost:<port>. 최대 2048바이트, 사용자 이름이나 비밀번호 없음, 쿼리 없음, 프래그먼트 없음. Collie가 여기에 /session/v1을(를) 추가합니다 |
| 토큰 | 최소 32바이트, 공백 없는 출력 가능한 ASCII. Collie는 hello을(를) 포함하여 모든 요청에 Authorization: Bearer <token>을(를) 보냅니다 |
| durable agent 검사 | 버전, hello, ready보다 먼저 토큰을 상수 시간으로 비교합니다. 토큰이 없거나 잘못된 경우 다른 내용 없이 순수한 401 { "code": "unauthorized" }만 반환합니다 |
| 리다이렉트 | Collie는 리디렉션을 따르지 않습니다. 3xx는 상태로 상위에 전달되므로 토큰이 다른 호스트로 전달되지 않습니다 |
| ETag | 응답을 압축하는 프록시는 태그를 W/"<epoch>-<rev>"(으)로 약화시킬 수 있습니다. 양쪽 모두 W/을(를) 제거한 상태로 비교합니다 |
| 거부 | 401 또는 403은 durable agent가 token-refused(으)로 도달할 수 없음을 나타냅니다 |
| 시간 초과 | 모든 읽기 및 쓰기에 5000 ms를 적용합니다. 절전 모드였던 durable agent가 콜드 상태로 깨어날 수 있기 때문입니다. starter에는 30000 ms를 적용합니다 |
| Collie의 요청 빈도 | 휴대폰이 감시 중일 때는 2초마다, 그 외에는 10초마다 폴링합니다. 다운되었거나 거부된 durable agent에는 최대 10초에 한 번만 요청합니다 |
각 타임아웃은 연결부터 마지막 바이트까지 전체 교환의 마감 시간입니다. TLS 환경에서는 304를 포함하여 모든 폴링이 호스트에서 비용을 청구할 수 있는 요청입니다.
제한 사항
Collie는 이 제한을 초과하는 항목을 자르거나 거부하므로, 제한을 준수하는 durable agent는 데이터를 잃지 않습니다.
| 구분 | 제한 |
|---|---|
| 스냅샷당 워크스페이스 수 | 64 |
| 스냅샷당 탭 수 | 256 |
| 스냅샷당 창 수 | 256 |
| 창당 열린 요청 수 | 50개, 오래된 항목 우선 |
permission의 옵션 수 | 6 |
choice 및 선택 필드의 옵션 수 | 8 |
form의 필드 수 | 6 |
| 스냅샷당 starter 수 | 50 |
| 창당 벨트 버튼 수 | 4개, 16자 레이블 |
| id | 1~128바이트, 제어 문자 없음, 공백 없음, /, ?, # 제외 |
| 요청 본문 | 64KiB, 초과 시 413 too-large |
| 응답 | hello 16KiB, snapshot 4MiB, events 8MiB, conversations 1MiB, items 8MiB, POST 16KiB |
| 응답당 이벤트 수 | 1000개. 뒤처진 판독기는 현재 뷰를 받으며, 최대 최신 항목 2000개를 받습니다. |
user, reply, thinking 또는 notice 항목의 텍스트 | 64KiB |
markdown 또는 code 항목의 텍스트 | 32KiB |
| 휴대폰이 보내는 텍스트 | 32KiB |
link 항목 | https:// 전용, 최대 2048자 |
| 기록 페이지 | 대화 100개 또는 항목 1000개 |
| 기록 커서 | 출력 가능한 ASCII 512바이트, 공백 없음 |
제한을 초과한 문자열은 잘리고 제어 문자 및 비가시 문자가 제거됩니다. 제한을 초과한 목록은 앞쪽 항목들을 유지합니다. 제한을 초과한 기록 페이지는 전혀 읽지 않습니다.
버전 및 상태를 알리는 헬로
현재 유선 프로토콜 버전은 1 하나뿐이며, Collie는 1..1을 사용합니다.
버전 2가 출시되면 Collie는 출시 후 한 번의 마이너 릴리스 동안 버전 1을 허용하며, 그다음 마이너 릴리스에서 지원을 중단합니다. 판독기는 알 수 없는 필드, 이벤트 유형, 항목 종류 또는 코드를 무시합니다. expiresAt이나 decidedBy처럼 버전 1 내부에 추가된 필드는 선택 사항입니다. 새로운 필수 필드, 기존 필드의 새로운 의미, 또는 제거된 필드는 새 버전을 요구합니다.
휴대폰이 알지 못하는 종류의 요청은 휴대폰에서 응답할 수 없는 것으로 표시되며, 버튼이 표시되지 않습니다.
두 범위가 겹치지 않으면 Collie는 durable agent로부터 더 이상 아무것도 읽지 않습니다. durable agent 에포크당 한 번씩 자체 버전을 포함하여 hello을 한 번 더 전송하므로 durable agent가 자체 측에서 불일치를 기록할 수 있습니다. durable agent는 두 범위를 모두 명시하는 refusal와 함께 409 incompatible로 응답합니다. 이것이 알림 hello입니다.
Collie는 거부하는 각 범위마다 로그에 한 줄을 기록하며, collie doctor에 두 범위가 모두 표시됩니다. 휴대폰의 durable agent 홈에도 동일한 문장이 표시됩니다. 예: "durable agent는 유선 v2를 사용하고, 이 Collie는 v1을 사용합니다. Collie나 에이전트 SDK를 업데이트하십시오." 더 오래된 쪽을 업데이트하십시오.
정확한 규칙이 있는 위치
WIRE.md은 모든 형태, 코드, 규칙을 담은 계약입니다.
그 배경이 되는 결정 사항은 저장소의 기록 문서에 있습니다.