diff options
Diffstat (limited to 'docs/design')
| -rw-r--r-- | docs/design/015-boundary-meaning.md | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/docs/design/015-boundary-meaning.md b/docs/design/015-boundary-meaning.md new file mode 100644 index 0000000..bdc68df --- /dev/null +++ b/docs/design/015-boundary-meaning.md @@ -0,0 +1,70 @@ +# 015 — 경계에서의 값: 들어온 값은 모든 길에서 같게 나온다 + +작성일: 2026-09-30. 상태: 구현, 검사로 고정. [108](../research/108-one-value-every-path.md)에서 정했다. + +앱의 값은 여러 경계를 지난다. 들어올 때 HTTP의 JSON이나 쿼리에서 메시지의 필드가 되고, 저장할 때 저장 형식이 되고, +보일 때 보기의 글자가 되고, 보낼 때 링크나 HTTP의 기록이 되어 다른 노드의 입력으로 옮겨진다. 이 문서는 그 모든 경계에서 +값의 뜻이 무엇이고, 무엇을 그대로 옮기고 무엇을 거절하는지를 정한다. + +한 줄로는 이렇다. **받아들인 값은 어느 길로 나오든 같다. 수는 비트까지(0의 부호만 빼고), text는 바이트까지. +받아들일 수 없는 값은 모든 들어오는 길이 거절하고, 거절한 사건은 아무것도 남기지 않는다.** + +## 수 + +- **들어올 때.** JSON의 수와 쿼리의 값(퍼센트 인코딩을 푼 뒤)은 JSON 수의 문법으로 읽는다. 부호 `+`, 앞의 0(`01`), + 점만 있는 것(`.5`, `1.`), 16진, `NaN`, `Infinity`는 받지 않는다. 글자가 뜻하는 값에 가장 가까운 binary64로 읽는다(정확히 + 반올림하고, 가운데는 짝수로). 그 값이 유한하지 않으면(`1e999`) 거절한다. +- **0에는 부호가 없다.** aup에서 −0과 0은 같은 값이다. 비교는 같고, `distinct`는 한 번 세고, 보기와 글자는 둘 다 `0`으로 + 쓴다. 저장과 전달은 비트를 그대로 옮기므로 −0이 −0으로 남을 수 있지만, aup 코드에서는 보이지 않는다. +- **저장.** 비트 그대로 돌아온다. 크기가 2^53 미만인 정수는 zigzag varint, 그 밖은 표시와 8바이트다. +- **보일 때.** 다시 읽으면 같은 binary64가 되는 가장 짧은 글자다. 1e15 미만의 정수는 점과 지수 없이 쓰고, 그 밖은 `%g` + 모양에 지수를 줄여 쓴다. +- **보낼 때.** 기록의 비트가 그대로 간다. 받는 입력의 모양이 다르면 이름으로 옮긴다([014](014-fields-by-name.md)). u32를 + number로 넓히는 것은 정확하다. + +## u32 + +- **들어올 때.** 숫자만 받는다. 부호, 소수, 지수(`1e3`도), 앞의 0은 안 되고, 0부터 4,294,967,295까지다. 그 밖은 거절한다. + JSON과 쿼리가 같다. +- 상태에서는 수다. +- **보낼 때.** 출력의 u32 필드에 준 수는 범위 안의 정수여야 한다. 아니면 그 사건이 실패한다. 아무것도 남지 않고, 보내지도 + 않는다. + +## text + +- **들어올 때.** JSON 문자열은 이스케이프를 풀고 서로게이트 짝을 합친다. 날 본문은 바이트 그대로다. 결과는 UTF-8이어야 + 한다. 짝 없는 서로게이트, 너무 긴 인코딩, U+10FFFF 너머, 잘린 바이트는 거절한다. JSON이면 400 `json`, 날 본문이면 + 422 `encoding`이다. +- 유효한 스칼라는 무엇이든 그대로 둔다. NUL, 제어 문자, U+2028과 U+2029, BOM, 비문자가 모두 그렇다. +- **저장과 전달.** 바이트 그대로다. +- **보일 때.** JSON 문자열(따옴표, 역슬래시, 제어 문자를 이스케이프)이다. 다시 읽으면 같은 바이트다. +- **답할 때.** `reply 메시지.필드`의 답은 그 필드의 바이트다. + +## 메시지의 모양 + +- **그룹.** JSON에서는 안의 객체이고, 쿼리에서는 점으로 이은 이름(`at.x`)이다. 모듈과 전달에서는 `at.x` 같은 이름의 필드다. +- **행(`list of 레코드`).** JSON 배열의 객체 하나가 행 하나이고, 목록의 저장 형식으로 옮겨진다. 수와 text는 위와 같다. + 메시지의 행은 모두 받거나 하나도 받지 않는다. +- **사건.** 사건은 모두 되거나 아무것도 되지 않는다. 실패한 사건은 상태를 바꾸지 않고 보내지 않는다. +- **전달.** 필드를 이름으로 받는다. 같은 종류이거나 넓히는 것이어야 하고, 빠진 필드는 0이나 빈 값이며, 모르는 필드는 + 받지 않고 기다린다([014](014-fields-by-name.md)). 한 번씩, 순서대로 적용한다. + +## 저장과 다시 읽기 + +- 재시작(로그에서), 체크포인트 뒤의 재시작(이미지에서), 모듈 교체(상태를 이름으로 잇는다)가 모두 같은 값을 낸다. +- 보기와 질의는 마지막 저장의 스냅숏에서 읽는다. 그 저장의 상태와 같다. + +## 검사 + +[`tests/check.py`](../../tests/check.py)의 `server_meaning`이 한 번에 본다. + +- 값: 수 22개(0과 −0, 2^53 부근, 가장 큰 수, 정규와 비정규의 경계, 반쯤에서의 언더플로, 1e21 부근), u32 넷, text 12개(한글, + 4바이트 UTF-8, 이스케이프, NUL, U+2028, BOM, 비문자, 4 KiB). +- 들어오는 길: JSON(ASCII로 이스케이프한 것과 UTF-8), 행, 쿼리와 날 본문, 링크(다른 순서, 넓힌 필드), HTTP 전달. +- 나오는 길: 보기, 질의, 답, 재시작, 체크포인트 뒤의 재시작, 모듈 교체, 두 번 중계한 노드. +- 거절할 값 39가지(수, u32, text, 행)가 모든 들어오는 길에서 거절되고, 어디에도 남지 않는다. + +전달이 한 번씩, 순서대로 적용되는 것은 링크의 검사들(`server_links_udp_lossy`, `server_links_moved`, `server_upgrade`)과 +[012](012-link-protocol.md)이 지킨다. 필드를 이름으로 받는 규칙은 `server_fields`가 지킨다. + +화면(Vega가 보기를 그리는 것)은 이 문서 밖이다. 다음 단계다. |