@things-factory/headless-twin 10.1.147 → 10.1.150
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist-server/service/reference/hook-contract.js +4 -1
- package/dist-server/service/reference/hook-contract.js.map +1 -1
- package/dist-server/service/reference/reference-hook.js +4 -1
- package/dist-server/service/reference/reference-hook.js.map +1 -1
- package/package.json +19 -7
- package/server/service/reference/hook-contract.ts +4 -1
- package/server/service/reference/reference-hook.ts +4 -1
- package/test/hook-address.test.ts +28 -0
- package/tsconfig.tsbuildinfo +1 -1
|
@@ -24,7 +24,10 @@ exports.producedInstance = producedInstance;
|
|
|
24
24
|
*
|
|
25
25
|
* ── 규약 ────────────────────────────────────────────────────────────────────
|
|
26
26
|
*
|
|
27
|
-
* 주소 POST /
|
|
27
|
+
* 주소 POST /twin/hook/<연결이름>/<트윈> — no /domain/<도메인> prefix: the route sits on the domain-public
|
|
28
|
+
* router without one (server/routes.ts:31); a prefixed address falls through and answers 405
|
|
29
|
+
* 도메인 X-Things-Factory-Domain: <도메인> — the webhook module sends it from the destination's
|
|
30
|
+
* params.receivingDomain
|
|
28
31
|
* 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다
|
|
29
32
|
* X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>
|
|
30
33
|
* 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hook-contract.js","sourceRoot":"","sources":["../../../server/service/reference/hook-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 웹훅의 규약 — 상태 코드 · 비밀값 · 어느 트윈인가.\n *\n * 데이터베이스를 부르는 부분과 갈라 둔다(§`reference-hook`): 규약만 있는 자리라야 시험이 엔티티를\n * 끌고 오지 않는다. 실제로 그것 때문에 시험이 서지 않았다.\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을\n * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로\n * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.\n *\n * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.\n *\n * ── 규약 ────────────────────────────────────────────────────────────────────\n *\n * 주소 POST /domain/<도메인>/twin/hook/<연결이름>/<트윈>\n * 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다\n * X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>\n * 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다\n * 응답 아래 §`hookStatus`\n *\n * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────\n * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서\n * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.\n *\n * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다\n * 훅을 못 쓰는 것이 낫습니다.\n *\n * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────\n * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,\n * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —\n * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로\n * 옮기면 약해지고 테스트가 없어집니다.\n *\n * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────\n * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서\n * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나\n * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.\n *\n * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────\n * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입\n * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지\n * 함께 알립니다.\n */\n/*\n * `WebhookResponse` comes from the root, not from `@operato/ops-contract/webhook`.\n *\n * That subpath resolves to `webhook-signature`, which is a separate module kept out of the barrel\n * because it pulls in `node:crypto`. The module actually named `webhook.ts` — status codes, the\n * envelope, the response — reaches consumers through the root barrel. Importing the response type\n * from the subpath fails with TS2305, which is what happened here first.\n */\nimport { checkSequence, type WebhookResponse } from '@operato/ops-contract'\nimport { WEBHOOK_HEADER, verifyWebhookSignature } from '@operato/ops-contract/webhook'\n\n/*\n * The body is typed by the contract, not by this file (2026-09-07).\n *\n * It was `Record<string, unknown>`, which accepts anything — so nothing checked that what we reply\n * with is what a sender was told to expect. It was not: the contract declared `rejected` in prose\n * only, operato-plant guessed \"a list of envelope ids\", and a whole batch was stamped delivered\n * while one envelope never landed (mes_outbox_events seq 178 — SENT, attempts 0, no error).\n *\n * With `WebhookResponse` here, adding a field to a reply without declaring it fails the build on\n * this side, which is the side that would otherwise ship the surprise.\n */\n/** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */\nexport interface HookOutcome {\n status: number\n body: WebhookResponse\n}\n\n/**\n * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).\n *\n * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-plant)에 또 있었다. 그래서 같은 409 를 양쪽이 다른\n * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.\n * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.\n *\n * 판정표는 만드는 쪽과 읽는 쪽이 합의해야 하는 것이라 계약 층에 있다(`@operato/ops-contract`).\n * `notLive` 가 409 에서 503 으로 옮겨진 이유도 그 파일에 적혀 있다.\n *\n * **여기서 이름을 바꿔 다시 내보내지 않는다.** 부르는 쪽은 `WEBHOOK_STATUS` 를 계약에서 바로 가져온다.\n * 별명을 두면 같은 표에 이름이 둘이 되고, 다음 사람이 어느 쪽이 정본인지 물어야 한다.\n */\n\n/** 헤더에서 비밀값을 꺼낸다 — 두 가지 방식을 받는다(밀어 주는 쪽의 관습이 갈린다). */\nexport function secretFromHeaders(headers: Record<string, unknown> | undefined): string {\n const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n const direct = pick('x-twin-hook-secret')\n if (direct) return direct\n const auth = pick('authorization')\n return auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : ''\n}\n\n/**\n * 비밀값 비교 — **길이가 다르면 바로 거절하고, 같으면 끝까지 비교한다.**\n *\n * 앞에서 다른 것을 발견하고 곧바로 답하면 응답 시간이 달라지고, 그 차이로 비밀값을 한 글자씩 알아낼 수\n * 있습니다. 그래서 같은 길이면 전부를 비교합니다.\n */\nexport function secretMatches(given: string, expected: string): boolean {\n if (!expected || !given || given.length !== expected.length) return false\n let diff = 0\n for (let i = 0; i < expected.length; i++) diff |= given.charCodeAt(i) ^ expected.charCodeAt(i)\n return diff === 0\n}\n\n/**\n * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**\n *\n * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에\n * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-plant)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로\n * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.\n *\n * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)\n * 파싱한 객체를 다시 문자열로 만들어 확인하고 싶어지는데, 키 순서와 공백이 달라져 어차피 맞지 않는다.\n * 맞지 않는 것을 통과시키면 서명이 있으나 마나 한 것이 된다.\n */\nexport function authorizeHook(args: {\n headers: Record<string, unknown> | undefined\n /** 받은 바이트 그대로. 서명을 쓰지 않는 연결에서는 없어도 된다. */\n rawBody: string | undefined\n /** 연결 설정에 저장된 비밀값. 서명과 비밀값이 같은 값을 쓴다. */\n secret: string\n nowMs: number\n}): { ok: true; method: 'signature' | 'secret' } | { ok: false; reason: string } {\n const { headers, rawBody, secret, nowMs } = args\n const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n const signature = pick(WEBHOOK_HEADER.signature)\n\n if (signature) {\n if (rawBody === undefined) {\n return { ok: false, reason: 'signed request but the raw body was not kept — cannot verify' }\n }\n const verdict = verifyWebhookSignature({\n secret,\n timestamp: pick(WEBHOOK_HEADER.timestamp),\n signature,\n body: rawBody,\n nowMs\n })\n /* `=== false` 로 본다 — 이 저장소는 `strictNullChecks` 가 꺼져 있어 참·거짓만으로는 좁혀지지 않는다. */\n if (verdict.ok === false) return { ok: false, reason: `signature ${verdict.reason}` }\n return { ok: true, method: 'signature' }\n }\n\n return secretMatches(secretFromHeaders(headers), secret)\n ? { ok: true, method: 'secret' }\n : { ok: false, reason: 'hook secret does not match' }\n}\n\n/**\n * 커서에 적을 열쇠 — **트윈까지 넣는다.**\n *\n * ── 왜 (2026-08-31, MES 레인 질문에서 나옴) ───────────────────────────────\n * 커서는 **연결마다** 한 행(`TwinReference.liveCursor`)에 산다. 그런데 연결 하나가 트윈 여럿을\n * 만든다(`scopeSpec.produced` 가 목록이다). 보내는 쪽의 단위 이름만으로 열쇠를 잡으면, 같은 연결의\n * 두 공장이 같은 이름(`EVENTS`)을 쓸 때 **한 계수기를 함께 쓴다.**\n *\n * 그러면 A 공장이 5까지 올린 뒤 B 공장이 1을 보내면 이미 본 번호가 되어 버려지고, A 가 6을 보내면\n * B 의 번호와 어긋나 끊임없이 「빠졌다」가 된다. 같은 부류가 이 저장소에서 이미 났다 — 두 공장의\n * 같은 번호가 한 자리에 겹쳤다.\n *\n * 보내는 쪽에 트윈 이름을 넣으라고 하지 않는다. 어디로 갈지는 주소가 이미 말했고, 그것을 본문에도\n * 적으라고 하면 둘이 어긋나는 날 어느 쪽을 믿을지 정해야 한다.\n */\nexport function pushCursorKey(instanceId: string, scope: string): string {\n return `${instanceId}::${scope}`\n}\n\n/**\n * 커서에서 그 단위의 마지막 번호를 꺼낸다.\n *\n * 커서 모양은 `{ streams: { [흐름]: { since?, seen[], seq? } } }` 이고 **흐름 이름은 어댑터가 정한다**\n * (§`TwinReference.liveCursor`). 밀어 주는 연결에서는 그 이름이 곧 번호를 매기는 단위다.\n *\n * 자리를 따로 만들지 않는 이유는 「재기동을 넘어 사는 진행 위치」가 두 벌이 되기 때문이다. 폴링이 쓰는\n * `since` 와 밀어 주기가 쓰는 `seq` 는 둘 다 「이 흐름을 어디까지 읽었나」이고 원본이 되풀어 줄 수 있다.\n */\nexport function seqOf(cursor: unknown, scope: string): number | undefined {\n const streams = (cursor as any)?.streams\n const seq = streams?.[scope]?.seq\n return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */\nexport function withSeq(cursor: unknown, scope: string, seq: number, firstSeq?: number): Record<string, unknown> {\n const base = (cursor && typeof cursor === 'object' ? (cursor as Record<string, unknown>) : {}) as Record<string, any>\n const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {}\n const prev = streams[scope] ?? {}\n /*\n * **`firstSeq` 는 한 번만 적힌다.** 이 연결이 이 단위를 몇 번부터 받기 시작했는지는 바뀌지 않는\n * 사실이고, 나중에 덮으면 「앞이 비었나」를 다시 물을 수 없다.\n *\n * 그래서 첫 봉투 판정이 있을 때만 넘어온다(`SequencedTake.firstSeq`). 커서가 이미 나아간 뒤에\n * 이 값을 만들면 그 번호는 첫 번호가 아니라 그때 마침 온 번호다.\n */\n streams[scope] = { ...prev, seq, ...(firstSeq !== undefined && prev.firstSeq === undefined ? { firstSeq } : {}) }\n return { ...base, streams }\n}\n\n/**\n * 이 연결이 이 단위를 **몇 번부터 받기 시작했나** — 적힌 적이 없으면 `undefined`.\n *\n * 「앞이 비었나」를 답하려면 이 값이 있어야 한다. 없으면 **모른다고 말해야 한다** — 0 으로 답하면\n * 1번부터 다 받은 것으로 읽힌다.\n */\nexport function firstSeqOf(cursor: unknown, scope: string): number | undefined {\n const seq = (cursor as any)?.streams?.[scope]?.firstSeq\n return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/**\n * **번호대로 받을 수 있는 데까지 자른다** — 밀어 받는 길과 backfill 하는 길이 이 함수 하나를 지난다.\n *\n * ── 왜 갈라 두나 (2026-08-31) ────────────────────────────────────────────\n * 이 판정이 훅 안에 박혀 있었다. backfill(`fetchSince`)이 같은 판정을 해야 하는데, 거기서 다시 만들면\n * **두 길이 다른 규칙으로 받는다** — 한쪽만 고쳐지는 날이 오고, 어긋난 그 길에서만 사실이 사라진다.\n *\n * 번호 확인을 커넥터가 아니라 프레임워크로 가져온 것과 같은 이유다. 자리가 하나여야 한다.\n *\n * ── 첫 구멍에서 멈춘다 ───────────────────────────────────────────────────\n * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽은 `expectedSeq` 부터 다시\n * 보내고, 뒤엣것은 그때 함께 온다.\n */\nexport interface SequencedTake {\n /** 받아들인 레코드 — 구멍 앞까지다. */\n records: unknown[]\n /** 번호를 확인했나. 번호를 매기지 않는 원본은 거짓이고, 그 사실을 응답에 남긴다. */\n numbered: boolean\n /** 커서에 적을 번호 — 받은 것이 없으면 없다. */\n advancedSeq?: number\n /** 구멍이 났다 — 그 앞부터 다시 받아야 한다. */\n gap?: { expectedSeq: number; lastSeq: number }\n /**\n * 이 단위의 **첫 봉투였다** — 그 앞으로 몇 개를 못 봤나.\n *\n * ── 왜 이 칸이 생겼나 (2026-09-06 실측) ──────────────────────────────────\n * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 다음에 온 21번이 첫 봉투로\n * 앉으며 **커서가 21 로 뛰었다.** 커서가 0 이었다면 같은 21이 구멍이었다.\n *\n * 스무 건이 없는데 구멍으로도 안 세어지고, 경고도 없고, backfill 대상도 아니었다 — backfill 은 커서부터\n * 묻는다. 그 사실이 아무 데도 안 남았다.\n *\n * **손실이라고 말하지 않는다.** 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 그 아래는 애초에\n * 안 받기로 한 것이다. 계약은 둘을 구별할 수 없으므로 수만 낸다.\n *\n * 0 이면 1번부터 시작한 것이라 이 칸을 내지 않는다 — 말할 것이 없다.\n */\n firstUnseenBefore?: number\n /**\n * 이 묶음의 첫 봉투가 **이 단위의 첫 봉투였다** — 그 번호.\n *\n * `firstUnseenBefore` 와 다르다: 이쪽은 1번부터 시작한 연결에도 있다(값 1). 커서에 적어 두면\n * 나중에 「앞이 비었나」를 답할 수 있다.\n */\n firstSeq?: number\n /**\n * 이 묶음에서 **가장 낮게 받아들인 번호** — 하나도 못 받았으면 없다.\n *\n * `firstSeq` 와 다르다. `firstSeq` 는 「이 단위의 첫 봉투였다」일 때만 있고, 이쪽은 언제나 있다.\n *\n * 밑에서부터 다시 받을 때 이것이 필요하다. `from: 0` 으로 부르면 커서가 0 이므로 seq 1 은\n * `next` 판정이고 `firstSeq` 가 안 생긴다 — 그런데 우리는 실제로 1번부터 갖게 된다. 그 사실을\n * 적어야 「앞이 비었나」에 답할 수 있다.\n */\n lowestSeq?: number\n /**\n * 받을 수 없는 묶음 — 그 이유.\n *\n * 번호가 있는 봉투와 없는 봉투가 섞였거나 번호가 정수가 아니다. 둘 다 보내는 쪽의 결함이고,\n * **반쯤 확인한 것을 확인했다고 말하지 않는다.**\n */\n refused?: string\n}\n\nexport function takeInSequence(args: {\n items: { record: unknown; seq?: number; at?: string }[]\n scope?: string\n /** 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`. */\n lastSeq?: number\n}): SequencedTake {\n const { items, scope, lastSeq } = args\n\n const withSeq = items.filter(i => typeof i?.seq === 'number').length\n if (withSeq && withSeq !== items.length) {\n return { records: [], numbered: false, refused: `mixed batch — ${withSeq} of ${items.length} items carry a sequence number` }\n }\n const numbered = withSeq > 0 && !!scope\n\n if (!numbered) return { records: items.map(i => i.record), numbered: false }\n\n let cursor = lastSeq\n let take = 0\n let gap: { expectedSeq: number; lastSeq: number } | undefined\n /* 첫 봉투가 몇 번부터 시작했나 — 그 앞을 못 본 사실을 응답에 남긴다. */\n let firstUnseenBefore: number | undefined\n /* 이 단위를 몇 번부터 받기 시작했나 — 커서에 적어 두면 「앞이 비었나」를 나중에 답할 수 있다. */\n let firstSeq: number | undefined\n /* 이 묶음에서 가장 낮게 받아들인 번호 — 밑에서부터 다시 받을 때 이것이 firstSeq 가 된다. */\n let lowestSeq: number | undefined\n for (const item of items) {\n let verdict\n try {\n verdict = checkSequence(cursor, item.seq as number)\n } catch (e: any) {\n return { records: [], numbered: true, refused: e?.message ?? 'bad sequence number' }\n }\n if (verdict.kind === 'gap') {\n gap = { expectedSeq: verdict.expectedSeq, lastSeq: verdict.lastSeq }\n break\n }\n if (verdict.kind === 'first') {\n firstSeq = item.seq as number\n /*\n * 계약이 `unseenBefore` 를 내면 그것을 쓴다. 설치된 판이 그보다 오래됐으면 번호에서 센다 —\n * 첫 봉투의 번호 아래로 그만큼이 있고 우리는 그것을 받은 적이 없다.\n *\n * ⚠ 이 두 번째 길은 계약 0.9.9 가 깔리면 지운다. 그때까지 두는 이유는, 계약을 기다리며\n * 비워 두면 **코드는 있는데 아무 일도 안 하는 상태**가 되고 그것이 이 결함의 원인과 같은\n * 모양이기 때문이다.\n */\n const unseen = (verdict as any).unseenBefore ?? (item.seq as number) - 1\n if (unseen > 0) firstUnseenBefore = unseen\n }\n if (lowestSeq === undefined) lowestSeq = item.seq as number\n cursor = verdict.lastSeq\n take++\n }\n\n return {\n /*\n * **봉투의 시각을 레코드에 얹는다** — 레코드가 자기 시각을 말하면 그것이 이긴다.\n *\n * 시각을 안 싣는 레코드는 ingest 시각으로 떨어지고, 그 값이 실행할 때마다 달라서 fact identity 가\n * 매번 바뀐다. 그래서 같은 사실을 다시 받으면 dedupe 가 안 되고 새 사실로 앉는다 —\n * `fillTwinScope` 를 두 번 돌렸더니 저널이 40 → 69건이 됐다(2026-09-06 측정).\n */\n records: items.slice(0, take).map(i => {\n const r = i.record as any\n if (!i.at || r == null || typeof r !== 'object') return i.record\n return r.at === undefined && r.eventTime === undefined ? { ...r, at: i.at } : i.record\n }),\n numbered: true,\n /* 앞의 것을 하나도 못 받았으면 커서를 올릴 것이 없다. */\n ...(take > 0 && typeof cursor === 'number' ? { advancedSeq: cursor } : {}),\n ...(gap ? { gap } : {}),\n ...(firstUnseenBefore ? { firstUnseenBefore } : {}),\n ...(firstSeq !== undefined ? { firstSeq } : {}),\n ...(lowestSeq !== undefined ? { lowestSeq } : {})\n }\n}\n\n/** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */\nexport function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {\n const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []\n const hit = produced.find(p => String(p?.instanceId ?? '') === instanceId)\n return hit?.siteId ? { siteId: String(hit.siteId) } : undefined\n}\n\n"]}
|
|
1
|
+
{"version":3,"file":"hook-contract.js","sourceRoot":"","sources":["../../../server/service/reference/hook-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 웹훅의 규약 — 상태 코드 · 비밀값 · 어느 트윈인가.\n *\n * 데이터베이스를 부르는 부분과 갈라 둔다(§`reference-hook`): 규약만 있는 자리라야 시험이 엔티티를\n * 끌고 오지 않는다. 실제로 그것 때문에 시험이 서지 않았다.\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을\n * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로\n * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.\n *\n * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.\n *\n * ── 규약 ────────────────────────────────────────────────────────────────────\n *\n * 주소 POST /twin/hook/<연결이름>/<트윈> — no /domain/<도메인> prefix: the route sits on the domain-public\n * router without one (server/routes.ts:31); a prefixed address falls through and answers 405\n * 도메인 X-Things-Factory-Domain: <도메인> — the webhook module sends it from the destination's\n * params.receivingDomain\n * 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다\n * X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>\n * 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다\n * 응답 아래 §`hookStatus`\n *\n * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────\n * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서\n * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.\n *\n * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다\n * 훅을 못 쓰는 것이 낫습니다.\n *\n * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────\n * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,\n * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —\n * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로\n * 옮기면 약해지고 테스트가 없어집니다.\n *\n * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────\n * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서\n * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나\n * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.\n *\n * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────\n * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입\n * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지\n * 함께 알립니다.\n */\n/*\n * `WebhookResponse` comes from the root, not from `@operato/ops-contract/webhook`.\n *\n * That subpath resolves to `webhook-signature`, which is a separate module kept out of the barrel\n * because it pulls in `node:crypto`. The module actually named `webhook.ts` — status codes, the\n * envelope, the response — reaches consumers through the root barrel. Importing the response type\n * from the subpath fails with TS2305, which is what happened here first.\n */\nimport { checkSequence, type WebhookResponse } from '@operato/ops-contract'\nimport { WEBHOOK_HEADER, verifyWebhookSignature } from '@operato/ops-contract/webhook'\n\n/*\n * The body is typed by the contract, not by this file (2026-09-07).\n *\n * It was `Record<string, unknown>`, which accepts anything — so nothing checked that what we reply\n * with is what a sender was told to expect. It was not: the contract declared `rejected` in prose\n * only, operato-plant guessed \"a list of envelope ids\", and a whole batch was stamped delivered\n * while one envelope never landed (mes_outbox_events seq 178 — SENT, attempts 0, no error).\n *\n * With `WebhookResponse` here, adding a field to a reply without declaring it fails the build on\n * this side, which is the side that would otherwise ship the surprise.\n */\n/** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */\nexport interface HookOutcome {\n status: number\n body: WebhookResponse\n}\n\n/**\n * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).\n *\n * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-plant)에 또 있었다. 그래서 같은 409 를 양쪽이 다른\n * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.\n * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.\n *\n * 판정표는 만드는 쪽과 읽는 쪽이 합의해야 하는 것이라 계약 층에 있다(`@operato/ops-contract`).\n * `notLive` 가 409 에서 503 으로 옮겨진 이유도 그 파일에 적혀 있다.\n *\n * **여기서 이름을 바꿔 다시 내보내지 않는다.** 부르는 쪽은 `WEBHOOK_STATUS` 를 계약에서 바로 가져온다.\n * 별명을 두면 같은 표에 이름이 둘이 되고, 다음 사람이 어느 쪽이 정본인지 물어야 한다.\n */\n\n/** 헤더에서 비밀값을 꺼낸다 — 두 가지 방식을 받는다(밀어 주는 쪽의 관습이 갈린다). */\nexport function secretFromHeaders(headers: Record<string, unknown> | undefined): string {\n const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n const direct = pick('x-twin-hook-secret')\n if (direct) return direct\n const auth = pick('authorization')\n return auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : ''\n}\n\n/**\n * 비밀값 비교 — **길이가 다르면 바로 거절하고, 같으면 끝까지 비교한다.**\n *\n * 앞에서 다른 것을 발견하고 곧바로 답하면 응답 시간이 달라지고, 그 차이로 비밀값을 한 글자씩 알아낼 수\n * 있습니다. 그래서 같은 길이면 전부를 비교합니다.\n */\nexport function secretMatches(given: string, expected: string): boolean {\n if (!expected || !given || given.length !== expected.length) return false\n let diff = 0\n for (let i = 0; i < expected.length; i++) diff |= given.charCodeAt(i) ^ expected.charCodeAt(i)\n return diff === 0\n}\n\n/**\n * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**\n *\n * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에\n * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-plant)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로\n * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.\n *\n * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)\n * 파싱한 객체를 다시 문자열로 만들어 확인하고 싶어지는데, 키 순서와 공백이 달라져 어차피 맞지 않는다.\n * 맞지 않는 것을 통과시키면 서명이 있으나 마나 한 것이 된다.\n */\nexport function authorizeHook(args: {\n headers: Record<string, unknown> | undefined\n /** 받은 바이트 그대로. 서명을 쓰지 않는 연결에서는 없어도 된다. */\n rawBody: string | undefined\n /** 연결 설정에 저장된 비밀값. 서명과 비밀값이 같은 값을 쓴다. */\n secret: string\n nowMs: number\n}): { ok: true; method: 'signature' | 'secret' } | { ok: false; reason: string } {\n const { headers, rawBody, secret, nowMs } = args\n const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n const signature = pick(WEBHOOK_HEADER.signature)\n\n if (signature) {\n if (rawBody === undefined) {\n return { ok: false, reason: 'signed request but the raw body was not kept — cannot verify' }\n }\n const verdict = verifyWebhookSignature({\n secret,\n timestamp: pick(WEBHOOK_HEADER.timestamp),\n signature,\n body: rawBody,\n nowMs\n })\n /* `=== false` 로 본다 — 이 저장소는 `strictNullChecks` 가 꺼져 있어 참·거짓만으로는 좁혀지지 않는다. */\n if (verdict.ok === false) return { ok: false, reason: `signature ${verdict.reason}` }\n return { ok: true, method: 'signature' }\n }\n\n return secretMatches(secretFromHeaders(headers), secret)\n ? { ok: true, method: 'secret' }\n : { ok: false, reason: 'hook secret does not match' }\n}\n\n/**\n * 커서에 적을 열쇠 — **트윈까지 넣는다.**\n *\n * ── 왜 (2026-08-31, MES 레인 질문에서 나옴) ───────────────────────────────\n * 커서는 **연결마다** 한 행(`TwinReference.liveCursor`)에 산다. 그런데 연결 하나가 트윈 여럿을\n * 만든다(`scopeSpec.produced` 가 목록이다). 보내는 쪽의 단위 이름만으로 열쇠를 잡으면, 같은 연결의\n * 두 공장이 같은 이름(`EVENTS`)을 쓸 때 **한 계수기를 함께 쓴다.**\n *\n * 그러면 A 공장이 5까지 올린 뒤 B 공장이 1을 보내면 이미 본 번호가 되어 버려지고, A 가 6을 보내면\n * B 의 번호와 어긋나 끊임없이 「빠졌다」가 된다. 같은 부류가 이 저장소에서 이미 났다 — 두 공장의\n * 같은 번호가 한 자리에 겹쳤다.\n *\n * 보내는 쪽에 트윈 이름을 넣으라고 하지 않는다. 어디로 갈지는 주소가 이미 말했고, 그것을 본문에도\n * 적으라고 하면 둘이 어긋나는 날 어느 쪽을 믿을지 정해야 한다.\n */\nexport function pushCursorKey(instanceId: string, scope: string): string {\n return `${instanceId}::${scope}`\n}\n\n/**\n * 커서에서 그 단위의 마지막 번호를 꺼낸다.\n *\n * 커서 모양은 `{ streams: { [흐름]: { since?, seen[], seq? } } }` 이고 **흐름 이름은 어댑터가 정한다**\n * (§`TwinReference.liveCursor`). 밀어 주는 연결에서는 그 이름이 곧 번호를 매기는 단위다.\n *\n * 자리를 따로 만들지 않는 이유는 「재기동을 넘어 사는 진행 위치」가 두 벌이 되기 때문이다. 폴링이 쓰는\n * `since` 와 밀어 주기가 쓰는 `seq` 는 둘 다 「이 흐름을 어디까지 읽었나」이고 원본이 되풀어 줄 수 있다.\n */\nexport function seqOf(cursor: unknown, scope: string): number | undefined {\n const streams = (cursor as any)?.streams\n const seq = streams?.[scope]?.seq\n return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */\nexport function withSeq(cursor: unknown, scope: string, seq: number, firstSeq?: number): Record<string, unknown> {\n const base = (cursor && typeof cursor === 'object' ? (cursor as Record<string, unknown>) : {}) as Record<string, any>\n const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {}\n const prev = streams[scope] ?? {}\n /*\n * **`firstSeq` 는 한 번만 적힌다.** 이 연결이 이 단위를 몇 번부터 받기 시작했는지는 바뀌지 않는\n * 사실이고, 나중에 덮으면 「앞이 비었나」를 다시 물을 수 없다.\n *\n * 그래서 첫 봉투 판정이 있을 때만 넘어온다(`SequencedTake.firstSeq`). 커서가 이미 나아간 뒤에\n * 이 값을 만들면 그 번호는 첫 번호가 아니라 그때 마침 온 번호다.\n */\n streams[scope] = { ...prev, seq, ...(firstSeq !== undefined && prev.firstSeq === undefined ? { firstSeq } : {}) }\n return { ...base, streams }\n}\n\n/**\n * 이 연결이 이 단위를 **몇 번부터 받기 시작했나** — 적힌 적이 없으면 `undefined`.\n *\n * 「앞이 비었나」를 답하려면 이 값이 있어야 한다. 없으면 **모른다고 말해야 한다** — 0 으로 답하면\n * 1번부터 다 받은 것으로 읽힌다.\n */\nexport function firstSeqOf(cursor: unknown, scope: string): number | undefined {\n const seq = (cursor as any)?.streams?.[scope]?.firstSeq\n return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/**\n * **번호대로 받을 수 있는 데까지 자른다** — 밀어 받는 길과 backfill 하는 길이 이 함수 하나를 지난다.\n *\n * ── 왜 갈라 두나 (2026-08-31) ────────────────────────────────────────────\n * 이 판정이 훅 안에 박혀 있었다. backfill(`fetchSince`)이 같은 판정을 해야 하는데, 거기서 다시 만들면\n * **두 길이 다른 규칙으로 받는다** — 한쪽만 고쳐지는 날이 오고, 어긋난 그 길에서만 사실이 사라진다.\n *\n * 번호 확인을 커넥터가 아니라 프레임워크로 가져온 것과 같은 이유다. 자리가 하나여야 한다.\n *\n * ── 첫 구멍에서 멈춘다 ───────────────────────────────────────────────────\n * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽은 `expectedSeq` 부터 다시\n * 보내고, 뒤엣것은 그때 함께 온다.\n */\nexport interface SequencedTake {\n /** 받아들인 레코드 — 구멍 앞까지다. */\n records: unknown[]\n /** 번호를 확인했나. 번호를 매기지 않는 원본은 거짓이고, 그 사실을 응답에 남긴다. */\n numbered: boolean\n /** 커서에 적을 번호 — 받은 것이 없으면 없다. */\n advancedSeq?: number\n /** 구멍이 났다 — 그 앞부터 다시 받아야 한다. */\n gap?: { expectedSeq: number; lastSeq: number }\n /**\n * 이 단위의 **첫 봉투였다** — 그 앞으로 몇 개를 못 봤나.\n *\n * ── 왜 이 칸이 생겼나 (2026-09-06 실측) ──────────────────────────────────\n * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 다음에 온 21번이 첫 봉투로\n * 앉으며 **커서가 21 로 뛰었다.** 커서가 0 이었다면 같은 21이 구멍이었다.\n *\n * 스무 건이 없는데 구멍으로도 안 세어지고, 경고도 없고, backfill 대상도 아니었다 — backfill 은 커서부터\n * 묻는다. 그 사실이 아무 데도 안 남았다.\n *\n * **손실이라고 말하지 않는다.** 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 그 아래는 애초에\n * 안 받기로 한 것이다. 계약은 둘을 구별할 수 없으므로 수만 낸다.\n *\n * 0 이면 1번부터 시작한 것이라 이 칸을 내지 않는다 — 말할 것이 없다.\n */\n firstUnseenBefore?: number\n /**\n * 이 묶음의 첫 봉투가 **이 단위의 첫 봉투였다** — 그 번호.\n *\n * `firstUnseenBefore` 와 다르다: 이쪽은 1번부터 시작한 연결에도 있다(값 1). 커서에 적어 두면\n * 나중에 「앞이 비었나」를 답할 수 있다.\n */\n firstSeq?: number\n /**\n * 이 묶음에서 **가장 낮게 받아들인 번호** — 하나도 못 받았으면 없다.\n *\n * `firstSeq` 와 다르다. `firstSeq` 는 「이 단위의 첫 봉투였다」일 때만 있고, 이쪽은 언제나 있다.\n *\n * 밑에서부터 다시 받을 때 이것이 필요하다. `from: 0` 으로 부르면 커서가 0 이므로 seq 1 은\n * `next` 판정이고 `firstSeq` 가 안 생긴다 — 그런데 우리는 실제로 1번부터 갖게 된다. 그 사실을\n * 적어야 「앞이 비었나」에 답할 수 있다.\n */\n lowestSeq?: number\n /**\n * 받을 수 없는 묶음 — 그 이유.\n *\n * 번호가 있는 봉투와 없는 봉투가 섞였거나 번호가 정수가 아니다. 둘 다 보내는 쪽의 결함이고,\n * **반쯤 확인한 것을 확인했다고 말하지 않는다.**\n */\n refused?: string\n}\n\nexport function takeInSequence(args: {\n items: { record: unknown; seq?: number; at?: string }[]\n scope?: string\n /** 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`. */\n lastSeq?: number\n}): SequencedTake {\n const { items, scope, lastSeq } = args\n\n const withSeq = items.filter(i => typeof i?.seq === 'number').length\n if (withSeq && withSeq !== items.length) {\n return { records: [], numbered: false, refused: `mixed batch — ${withSeq} of ${items.length} items carry a sequence number` }\n }\n const numbered = withSeq > 0 && !!scope\n\n if (!numbered) return { records: items.map(i => i.record), numbered: false }\n\n let cursor = lastSeq\n let take = 0\n let gap: { expectedSeq: number; lastSeq: number } | undefined\n /* 첫 봉투가 몇 번부터 시작했나 — 그 앞을 못 본 사실을 응답에 남긴다. */\n let firstUnseenBefore: number | undefined\n /* 이 단위를 몇 번부터 받기 시작했나 — 커서에 적어 두면 「앞이 비었나」를 나중에 답할 수 있다. */\n let firstSeq: number | undefined\n /* 이 묶음에서 가장 낮게 받아들인 번호 — 밑에서부터 다시 받을 때 이것이 firstSeq 가 된다. */\n let lowestSeq: number | undefined\n for (const item of items) {\n let verdict\n try {\n verdict = checkSequence(cursor, item.seq as number)\n } catch (e: any) {\n return { records: [], numbered: true, refused: e?.message ?? 'bad sequence number' }\n }\n if (verdict.kind === 'gap') {\n gap = { expectedSeq: verdict.expectedSeq, lastSeq: verdict.lastSeq }\n break\n }\n if (verdict.kind === 'first') {\n firstSeq = item.seq as number\n /*\n * 계약이 `unseenBefore` 를 내면 그것을 쓴다. 설치된 판이 그보다 오래됐으면 번호에서 센다 —\n * 첫 봉투의 번호 아래로 그만큼이 있고 우리는 그것을 받은 적이 없다.\n *\n * ⚠ 이 두 번째 길은 계약 0.9.9 가 깔리면 지운다. 그때까지 두는 이유는, 계약을 기다리며\n * 비워 두면 **코드는 있는데 아무 일도 안 하는 상태**가 되고 그것이 이 결함의 원인과 같은\n * 모양이기 때문이다.\n */\n const unseen = (verdict as any).unseenBefore ?? (item.seq as number) - 1\n if (unseen > 0) firstUnseenBefore = unseen\n }\n if (lowestSeq === undefined) lowestSeq = item.seq as number\n cursor = verdict.lastSeq\n take++\n }\n\n return {\n /*\n * **봉투의 시각을 레코드에 얹는다** — 레코드가 자기 시각을 말하면 그것이 이긴다.\n *\n * 시각을 안 싣는 레코드는 ingest 시각으로 떨어지고, 그 값이 실행할 때마다 달라서 fact identity 가\n * 매번 바뀐다. 그래서 같은 사실을 다시 받으면 dedupe 가 안 되고 새 사실로 앉는다 —\n * `fillTwinScope` 를 두 번 돌렸더니 저널이 40 → 69건이 됐다(2026-09-06 측정).\n */\n records: items.slice(0, take).map(i => {\n const r = i.record as any\n if (!i.at || r == null || typeof r !== 'object') return i.record\n return r.at === undefined && r.eventTime === undefined ? { ...r, at: i.at } : i.record\n }),\n numbered: true,\n /* 앞의 것을 하나도 못 받았으면 커서를 올릴 것이 없다. */\n ...(take > 0 && typeof cursor === 'number' ? { advancedSeq: cursor } : {}),\n ...(gap ? { gap } : {}),\n ...(firstUnseenBefore ? { firstUnseenBefore } : {}),\n ...(firstSeq !== undefined ? { firstSeq } : {}),\n ...(lowestSeq !== undefined ? { lowestSeq } : {})\n }\n}\n\n/** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */\nexport function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {\n const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []\n const hit = produced.find(p => String(p?.instanceId ?? '') === instanceId)\n return hit?.siteId ? { siteId: String(hit.siteId) } : undefined\n}\n\n"]}
|
|
@@ -17,7 +17,10 @@ exports.handleHook = handleHook;
|
|
|
17
17
|
*
|
|
18
18
|
* ── 규약 ────────────────────────────────────────────────────────────────────
|
|
19
19
|
*
|
|
20
|
-
* 주소 POST /
|
|
20
|
+
* 주소 POST /twin/hook/<연결이름>/<트윈> — no /domain/<도메인> prefix: the route sits on the domain-public
|
|
21
|
+
* router without one (server/routes.ts:31); a prefixed address falls through and answers 405
|
|
22
|
+
* 도메인 X-Things-Factory-Domain: <도메인> — the webhook module sends it from the destination's
|
|
23
|
+
* params.receivingDomain
|
|
21
24
|
* 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다
|
|
22
25
|
* X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>
|
|
23
26
|
* 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"reference-hook.js","sourceRoot":"","sources":["../../../server/service/reference/reference-hook.ts"],"names":[],"mappings":";;;AAgEA,gCAsRC;AAtVD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wDAA4E;AAE5E,gDAA8C;AAE9C,iEAAsE;AACtE,yDAA8E;AAC9E,uDAA8E;AAArE,qHAAA,iBAAiB,OAAA;AAC1B,yDAAqI;AAGrI,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/G,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,UAAU,CAAC,IAkChC;IACC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACpF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAA;IACtC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IAEtB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC9C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,MAAM,EAAE,6BAAc,CAAC,aAAa,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,MAAM,GAAG,EAAE,EAAE,CAAA;IAC/G,CAAC;IAED,MAAM,GAAG,GAAS,GAAW,CAAC,gBAAgB,IAAI,EAAE,CAAA;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACpD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,2CAA2C;QAC3C,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,SAAS;YAChC,IAAI,EAAE;gBACJ,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,eAAe,MAAM,oFAAoF;aACjH;SACF,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAA,gCAAa,EAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;IACzE,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,6BAAc,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAA;IACtF,CAAC;IAED,MAAM,IAAI,GAAG,IAAA,mCAAgB,EAAC,GAAU,EAAE,UAAU,CAAC,CAAA;IACrD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,aAAa;YACpC,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,UAAU,oCAAoC,MAAM,GAAG,EAAE;SAC7F,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAQ,IAAA,iCAAU,EAAC,MAAM,CAAE,GAAW,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAA;IACvE,IAAI,OAAO,OAAO,EAAE,aAAa,KAAK,UAAU,EAAE,CAAC;QACjD,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,WAAW;YAClC,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAe,GAAW,CAAC,WAAW,gDAAgD,EAAE;SACnH,CAAA;IACH,CAAC;IAED,IAAI,KAAmB,CAAA;IACvB,IAAI,CAAC;QACH,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACzD,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,yDAAyD;QACzD,OAAO,EAAE,MAAM,EAAE,6BAAc,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,IAAI,8BAA8B,EAAE,EAAE,CAAA;IACxH,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,EAAE,KAAK,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,UAAU;YACjC,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,8CAA8C,EAAE;SAC3E,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM,IAAI,GAAG,aAAa,CAAE,KAAa,CAAC,IAAI,CAAC,CAAA;IAC/C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,MAAM,EAAE,6BAAc,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,EAAE,CAAA;IAClG,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IACpG,qDAAqD;IACrD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAA,gCAAa,EAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAChE,MAAM,KAAK,GAAG,IAAA,iCAAc,EAAC;QAC3B,KAAK;QACL,KAAK;QACL,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,IAAA,wBAAK,EAAE,GAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;KAC/D,CAAC,CAAA;IACF,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,8BAA8B;QAC9B,OAAO,EAAE,MAAM,EAAE,6BAAc,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,CAAA;IACzF,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAA;IACrB;;;;;;OAMG;IACH,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC5B,IAAA,iBAAQ,EACN,kBAAkB,UAAU,OAAO,KAAK,IAAI,SAAS,MAAM,KAAK,CAAC,WAAW,mBAAmB;YAC7F,OAAO,KAAK,CAAC,iBAAiB,sCAAsC;YACpE,4BAA4B,CAC/B,CAAA;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IAE5G,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAA;IAE7B,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB;;;WAGG;QACH,IAAI,GAAG,EAAE,CAAC;YACR,IAAI,KAAK;gBAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;YACzB,OAAO,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAC/B,CAAC;QACD,IAAI,QAAQ;YAAE,MAAM,OAAO,CAAC,KAAK,EAAE,GAAU,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;QAC5F,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,EAAE;YACzB,IAAI,EAAE;gBACJ,EAAE,EAAE,IAAI;gBACR,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,CAAC;gBACV,UAAU,EAAE,CAAC;gBACb,UAAU,EAAE,CAAC;gBACb,QAAQ,EAAE,EAAE;gBACZ,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,iBAAiB,CAAC;aAC/D;SACF,CAAA;IACH,CAAC;IAED,IAAI,MAAoB,CAAA;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;IAClD,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,6BAAc,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,IAAI,eAAe,EAAE,EAAE,CAAA;IACrG,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAA;IACtC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,SAAS,GAAG,IAAA,oCAAiB,EAAC,QAAQ,EAAE,KAAkD,CAAC,CAAA;IAEjG,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,MAAM,CAAC,UAAU,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACnG;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACH,IAAA,iBAAQ,EACN,gBAAgB,UAAU,OAAO,OAAO,CAAC,MAAM,oBAAoB;YACjE,GAAG,iBAAiB,GAAG,IAAI,8CAA8C;YACzE,gDAAgD,CACnD,CAAA;QAED,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,OAAO;YAC9B,IAAI,EAAE;gBACJ,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,SAAS,UAAU,6CAA6C;gBACvE,OAAO,EAAE,OAAO,CAAC,MAAM;gBACvB,YAAY,EAAE,iBAAiB;aAChC;SACF,CAAA;IACH,CAAC;IAED,IAAI,QAAQ;QAAE,MAAM,OAAO,CAAC,KAAK,EAAE,GAAU,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;IAE5F;;;OAGG;IACH,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,KAAK;YAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;QACzB,OAAO,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;IACpD,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB;;;WAGG;QACH,OAAO;YACL,MAAM,EAAE,6BAAc,CAAC,OAAO;YAC9B,IAAI,EAAE;gBACJ,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,GAAG,QAAQ,CAAC,MAAM,OAAO,OAAO,CAAC,MAAM,kCAAkC;gBAChF,OAAO,EAAE,OAAO,CAAC,MAAM;gBACvB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC;gBAClC,QAAQ,EAAE,SAAS;gBACnB,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,iBAAiB,CAAC;aAC/D;SACF,CAAA;IACH,CAAC;IAED,OAAO;QACL,MAAM,EAAE,6BAAc,CAAC,EAAE;QACzB,IAAI,EAAE;YACJ,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,OAAO,CAAC,MAAM;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B;;;;eAIG;YACH,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC;YAClC,QAAQ,EAAE,EAAE;YACZ,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,iBAAiB,CAAC;SAC/D;KACF,CAAA;AACH,CAAC;AA0BD;;;;;GAKG;AACH;;;;;;GAMG;AACH,SAAS,UAAU,CACjB,KAAyB,EACzB,GAA6C;AAC7C;;;GAGG;AACH,WAAgC,EAAE,EAClC,QAAyC;IAEzC,OAAO;QACL,MAAM,EAAE,6BAAc,CAAC,WAAW;QAClC,IAAI,EAAE;YACJ,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,cAAc;YACrB,KAAK;YACL,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO;YACrC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzC;KACF,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAA;AAEhC;;;;;GAKG;AACH;;;;;;GAMG;AACH,SAAS,OAAO,CACd,KAAyB,EACzB,QAAoD,EACpD,QAAiB,EACjB,iBAA0B;IAE1B,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAA;IAChD,OAAO;QACL,eAAe,EAAE,IAAI;QACrB,KAAK;QACL,OAAO,EAAE,QAAQ,EAAE,GAAG;QACtB;;;WAGG;QACH,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,OAAO,CACpB,KAAgB,EAChB,GAAyC,EACzC,KAAa,EACb,GAAW,EACX,QAAiB;IAEjB,MAAM,IAAI,GAAG,IAAA,0BAAO,EAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1D,GAAG,CAAC,UAAU,GAAG,IAAI,CAAA;IACrB,MAAM,KAAK;SACR,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC;SACxB,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAA,iBAAQ,EAAC,+BAA+B,KAAK,IAAI,GAAG,OAAO,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC,CAAA;AACpG,CAAC","sourcesContent":["/*\n * 연결된 시스템이 **밀어 주는** 사실을 받는 자리 — 웹훅.\n *\n * 규약(상태 코드 · 비밀값 · 대상 확인)은 `hook-contract.ts` 에 있다. 여기는 그것을 써서 찾고 · 확인하고 ·\n * 커넥터에게 옮기게 하고 · 유입으로 넘기는 순서만 맡는다.\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을\n * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로\n * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.\n *\n * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.\n *\n * ── 규약 ────────────────────────────────────────────────────────────────────\n *\n * 주소 POST /domain/<도메인>/twin/hook/<연결이름>/<트윈>\n * 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다\n * X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>\n * 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다\n * 응답 아래 §`hookStatus`\n *\n * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────\n * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서\n * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.\n *\n * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다\n * 훅을 못 쓰는 것이 낫습니다.\n *\n * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────\n * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,\n * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —\n * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로\n * 옮기면 약해지고 테스트가 없어집니다.\n *\n * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────\n * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서\n * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나\n * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.\n *\n * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────\n * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입\n * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지\n * 함께 알립니다.\n */\nimport { WEBHOOK_STATUS, type WebhookResponse } from '@operato/ops-contract'\n\nimport { twinWarn } from '../../engine/log.js'\n\nimport { getAdapter, type InboundBatch } from './reference-adapter.js'\nimport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nexport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nimport { authorizeHook, producedInstance, pushCursorKey, seqOf, takeInSequence, withSeq, type HookOutcome } from './hook-contract.js'\n\ntype WebhookLane = 'FACTS' | 'ATTENTIONS'\nfunction webhookLaneOf(value: unknown): WebhookLane | undefined {\n return value === undefined || value === 'FACTS' ? 'FACTS' : value === 'ATTENTIONS' ? 'ATTENTIONS' : undefined\n}\n\n/**\n * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.\n *\n * 유입 자체(`ingest`)는 부르는 쪽이 넘겨 준다: 이 파일이 엔진을 직접 부르면 시험할 때 엔진이 필요해지고,\n * 그러면 규약을 확인하는 시험을 쓸 수 없다.\n */\nexport async function handleHook(args: {\n domainId: string\n source: string\n instanceId: string\n headers: Record<string, unknown>\n body: unknown\n /**\n * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다.\n *\n * 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다. 없으면 서명을 쓰는\n * 요청은 거절된다(§`authorizeHook`).\n */\n rawBody?: string\n /** 서명 창을 재는 기준 시각. 부르는 쪽이 준다 — 여기서 읽으면 시험이 시계에 매인다. */\n nowMs?: number\n /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */\n ingest: (instanceId: string, records: unknown[], lane: WebhookLane) => IngestResult | Promise<IngestResult>\n /**\n * 구멍을 봤다 — **부르는 쪽이 무엇을 할지 정한다.**\n *\n * 여기서 backfill 을 직접 부르지 않는다. 이 파일은 `ingest`·`store` 를 인자로 받아 가볍게 유지한다\n * (그래야 테스트가 엔진 없이 이 판정을 확인할 수 있다). backfill 을 import 하면 그 규율이 깨진다.\n *\n * 기다리지 않는 것도 부르는 쪽의 몫이다 — 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.\n */\n onGap?: (scope: string) => void\n /**\n * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**\n *\n * `ingest` 를 부르는 쪽이 넘겨 주는 것과 같은 이유다(위 §). 커서는 재기동을 넘어 살아야 하는데, 한\n * 프로세스 안에서만 확인하면 「적히나」는 보이지만 「다시 세우면 읽히나」는 안 보인다. 그 둘이 갈린\n * 결함을 이 저장소가 이미 겪었다.\n */\n store: HookStore\n}): Promise<HookOutcome> {\n const { domainId, source, instanceId, headers, body, rawBody, ingest, onGap } = args\n const nowMs = args.nowMs ?? Date.now()\n const { store } = args\n\n const ref = await store.load(domainId, source)\n if (!ref) {\n return { status: WEBHOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection \"${source}\"` } }\n }\n\n const cfg: any = (ref as any).connectionConfig ?? {}\n const expected = String(cfg.hookSecret ?? '').trim()\n if (!expected) {\n /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */\n return {\n status: WEBHOOK_STATUS.badSecret,\n body: {\n ok: false,\n error: `connection \"${source}\" declares no hookSecret — set one in the connection settings before pushing to it`\n }\n }\n }\n const auth = authorizeHook({ headers, rawBody, secret: expected, nowMs })\n if (auth.ok === false) {\n return { status: WEBHOOK_STATUS.badSecret, body: { ok: false, error: auth.reason } }\n }\n\n const site = producedInstance(ref as any, instanceId)\n if (!site) {\n return {\n status: WEBHOOK_STATUS.unknownTarget,\n body: { ok: false, error: `twin \"${instanceId}\" was not created by connection \"${source}\"` }\n }\n }\n\n const adapter: any = getAdapter(String((ref as any).adapterType ?? ''))\n if (typeof adapter?.handleInbound !== 'function') {\n return {\n status: WEBHOOK_STATUS.unsupported,\n body: { ok: false, error: `connector \"${(ref as any).adapterType}\" cannot take pushed events (no handleInbound)` }\n }\n }\n\n let batch: InboundBatch\n try {\n batch = adapter.handleInbound(cfg, site, body, headers)\n } catch (e: any) {\n /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */\n return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } }\n }\n const items = batch?.items\n if (!Array.isArray(items)) {\n return {\n status: WEBHOOK_STATUS.badPayload,\n body: { ok: false, error: 'the connector did not return a list of items' }\n }\n }\n\n /*\n * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.\n * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.\n *\n * 판정은 `takeInSequence` 하나가 한다 — **backfill 하는 길도 같은 함수를 지난다.** 여기서 따로 만들면\n * 두 길이 다른 규칙으로 받고, 한쪽만 고쳐지는 날이 온다.\n */\n const lane = webhookLaneOf((batch as any).lane)\n if (!lane) {\n return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: 'unknown webhook lane' } }\n }\n const scope = typeof batch.scope === 'string' && batch.scope.trim() ? batch.scope.trim() : undefined\n /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */\n const key = scope ? pushCursorKey(instanceId, scope) : undefined\n const taken = takeInSequence({\n items,\n scope,\n lastSeq: key ? seqOf((ref as any).liveCursor, key) : undefined\n })\n if (taken.refused) {\n /* 반쯤 확인한 것을 확인했다고 말하지 않는다. */\n return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: taken.refused } }\n }\n const numbered = taken.numbered\n const gap = taken.gap\n /*\n * 첫 봉투가 1번이 아니면 **그 사실을 남긴다.** 커서가 없는 연결에 21번이 오면 커서가 21 로 뛰고,\n * 그 앞 스무 건은 구멍으로도 안 세어진다. 실제로 plant 에서 그렇게 스무 건이 조용히 사라졌다.\n *\n * 손실이라고 말하지 않는다 — 늦게 붙은 트윈은 그 앞을 안 받기로 한 것이다. 수만 말하고 판단은\n * 사람이 한다.\n */\n if (taken.firstUnseenBefore) {\n twinWarn(\n `[twin-ingest] \"${instanceId}\" 의 ${scope ?? '(단위 없음)'} 를 ${taken.advancedSeq} 번부터 받기 시작했습니다 — ` +\n `그 앞 ${taken.firstUnseenBefore}건은 받은 적이 없습니다. 원본이 오래 돌고 있었으면 정상이고, ` +\n `보냈는데 못 받은 것이면 그만큼이 빠진 것입니다`\n )\n }\n const advanced = taken.advancedSeq !== undefined && key ? { scope: key, seq: taken.advancedSeq } : undefined\n\n const records = taken.records\n\n if (!records.length) {\n /*\n * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터\n * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.\n */\n if (gap) {\n if (scope) onGap?.(scope)\n return gapOutcome(scope, gap)\n }\n if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n return {\n status: WEBHOOK_STATUS.ok,\n body: {\n ok: true,\n offered: 0,\n applied: 0,\n duplicates: 0,\n vocabulary: 0,\n rejected: [],\n ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n }\n }\n }\n\n let result: IngestResult\n try {\n result = await ingest(instanceId, records, lane)\n } catch (e: any) {\n return { status: WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }\n }\n const rejected = result.rejected ?? []\n /*\n * ── 떨어진 것에 **봉투 id** 를 붙인다 (2026-09-07 측정) ──────────────────────\n * 이 응답이 `{ record, errors }` 목록이었고, plant 은 그것을 **봉투 id 문자열 목록**으로 읽고\n * 있었다. `Array.isArray` 는 통과하므로 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도\n * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.**\n *\n * 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 · 오류 없음 · 보냈음이었다. 우리가 말했는데\n * 상대가 못 알아듣는 모양이면, 말한 것이 아니다.\n *\n * 그래서 봉투 id 를 함께 싣는다. 보내는 쪽이 자기 행을 표시할 수 있고 까닭도 남는다.\n *\n * **id 를 못 찾으면 레코드를 그대로 싣는다.** 그때는 무엇이 떨어졌는지 알 방법이 그것뿐이고,\n * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다.\n *\n * 짝은 **객체 동일성**으로 짓는다. `records` 는 `items` 의 순서와 원소를 그대로 들고 있고\n * (§`takeInSequence`), 그래서 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면\n * 같은 모양의 레코드 둘이 서로의 id 를 가져간다.\n */\n const forCaller = rejectedForCaller(rejected, items as { record?: unknown; eventId?: unknown }[])\n\n if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0 && !result.vocabulary) {\n /*\n * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.\n * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.\n *\n * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이\n * 뜬 뒤에 그 구간이 비어 있게 된다.\n *\n * ── Vocabulary is why this test needs a fourth term (2026-09-07) ──────────\n * This inference reads an absence as a cause, and one absence is legitimate: a batch that was\n * entirely vocabulary applies no events, has no duplicates and rejects nothing, and yet\n * everything in it landed (§`applyMasterData`). Without the last term the receiver answers\n * 503 to correct traffic, and the sender then holds those facts and retries every thirty\n * seconds for as long as they keep arriving — the reply invents a reason (\"not running live\")\n * that the numbers do not support.\n *\n * Found by a test written for the response sum, not by reading this line.\n *\n * ── Why this branch has to say something out loud ─────────────────────────\n * Measured today: a 503 from here leaves **no trace on either side.** The sender maps it to\n * backpressure and returns without touching `attempts` or `lastError`, and this branch logged\n * nothing, so a sender re-offering the same batch every thirty seconds is invisible to both.\n *\n * That is also why \"it has not happened\" could not be established: `attempts 0` on the seven\n * vocabulary envelopes was offered as evidence and is not evidence, because this path never\n * increments that counter. Telling a sender to come back forever is worth one line.\n */\n twinWarn(\n `[twin-hook] \"${instanceId}\" 에 ${records.length}건이 왔는데 한 건도 앉지 않아 ` +\n `${NOT_LIVE_RETRY_MS / 1000}초 뒤 다시 오라고 답했습니다 — 트윈이 실시간으로 돌지 않는 것으로 봅니다. ` +\n `보내는 쪽은 이 답에 재시도 횟수를 남기지 않으므로, 되풀이되면 이 줄만 늘어납니다`\n )\n\n return {\n status: WEBHOOK_STATUS.notLive,\n body: {\n ok: false,\n error: `twin \"${instanceId}\" is not running live — nothing was applied`,\n offered: records.length,\n retryAfterMs: NOT_LIVE_RETRY_MS\n }\n }\n }\n\n if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n\n /*\n * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게\n * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.\n */\n if (gap) {\n if (scope) onGap?.(scope)\n return gapOutcome(scope, gap, forCaller, advanced)\n }\n\n if (rejected.length) {\n /*\n * **다시 보내라고 하지 않는다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,\n * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다.\n */\n return {\n status: WEBHOOK_STATUS.partial,\n body: {\n ok: false,\n error: `${rejected.length} of ${records.length} records did not pass validation`,\n offered: records.length,\n applied: result.applied,\n duplicates: result.duplicates,\n vocabulary: result.vocabulary ?? 0,\n rejected: forCaller,\n ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n }\n }\n }\n\n return {\n status: WEBHOOK_STATUS.ok,\n body: {\n ok: true,\n offered: records.length,\n applied: result.applied,\n duplicates: result.duplicates,\n /*\n * Always reported, even as zero — the sender's sum has a term for it either way, and a field\n * that appears only sometimes makes an absent one indistinguishable from a receiver that\n * does not count vocabulary at all.\n */\n vocabulary: result.vocabulary ?? 0,\n rejected: [],\n ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n }\n }\n}\n\n/**\n * 유입이 돌려주는 것.\n *\n * 떨어진 것을 **수가 아니라 목록으로** 받는다. 수만 받으면 보내는 쪽에 「몇 건이 떨어졌다」밖에 말할 수\n * 없고, 그러면 무엇을 따로 두어야 할지 알 수 없어 배치 전체를 다시 보내거나 전부 버린다.\n */\nexport interface IngestResult {\n applied: number\n duplicates: number\n rejected: { record: unknown; errors: string[] }[]\n /**\n * How many records were vocabulary rather than events — **needed so the reply's sum closes.**\n *\n * `liveIngest` has counted this all along and this boundary dropped it, because the callback was\n * typed as `IngestResult` and vocabulary was not on it. So `offered` counted those records and\n * none of the other three did, and a sender checking the sum would have seen a loss on ordinary\n * traffic (§`WebhookResponse.offered`).\n *\n * Optional because an ingest that handles no vocabulary need not say zero, and a caller that\n * simply does not know must not be made to claim none.\n */\n vocabulary?: number\n}\n\n/**\n * 구멍을 알리는 응답 — **앞의 것은 받았다는 것을 함께 말한다.**\n *\n * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서\n * 처리량만 먹는다.\n */\n/*\n * 구멍을 본 자리에서 **바로 받는다** — 번호가 비었다는 것을 아는 가장 이른 순간이다.\n *\n * 기다리지 않는다. 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번\n * 온다. 그리고 같은 단위를 1분 안에 두 번 부르지 않는다(§`FILL_DEBOUNCE_MS`) — 밀어 받는 쪽이\n * 구멍 뒤의 봉투를 계속 보내면 그때마다 구멍 판정이 나기 때문이다.\n */\nfunction gapOutcome(\n scope: string | undefined,\n gap: { expectedSeq: number; lastSeq: number },\n /*\n * 떨어진 것 — 봉투 id 를 알면 그것을, 모르면 레코드를 싣는다(§`InboundItem.eventId`).\n * 보내는 쪽이 자기 행을 찾을 수 있어야 하고, 못 찾으면 무엇이 떨어졌는지라도 보여야 한다.\n */\n rejected: RejectedForCaller[] = [],\n advanced?: { scope: string; seq: number }\n): HookOutcome {\n return {\n status: WEBHOOK_STATUS.sequenceGap,\n body: {\n ok: false,\n error: 'sequence gap',\n scope,\n expectedSeq: gap.expectedSeq,\n lastSeq: advanced?.seq ?? gap.lastSeq,\n ...(rejected.length ? { rejected } : {})\n }\n }\n}\n\n/**\n * 트윈이 안 돌 때 얼마나 쉬라고 할 것인가.\n *\n * 사람이 트윈을 띄워야 풀리므로 초 단위로 다시 두드릴 이유가 없다. 그렇다고 길게 잡으면 트윈이 뜬 뒤\n * 그만큼 늦게 이어진다.\n */\nconst NOT_LIVE_RETRY_MS = 30_000\n\n/**\n * 응답에 번호를 어떻게 적나 — **확인한 것과 확인하지 않은 것을 구별한다.**\n *\n * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느\n * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.\n */\n/*\n * The return type is the contract's, narrowed to the fields this function fills.\n *\n * It was `Record<string, unknown>`, and because the result is **spread** into the reply, an index\n * signature slips past the excess-property check entirely — the four fields below were unverified\n * even after `HookOutcome.body` was typed. Naming them here is what makes the check reach them.\n */\nfunction seqBody(\n scope: string | undefined,\n advanced: { scope: string; seq: number } | undefined,\n numbered: boolean,\n firstUnseenBefore?: number\n): Pick<WebhookResponse, 'sequenceChecked' | 'scope' | 'lastSeq' | 'firstUnseenBefore'> {\n if (!numbered) return { sequenceChecked: false }\n return {\n sequenceChecked: true,\n scope,\n lastSeq: advanced?.seq,\n /*\n * 첫 봉투였고 그 앞을 못 봤으면 **그 수를 보내는 쪽에 돌려준다.** 안 돌려주면 그 사실이 아무 데도\n * 안 남는다 — 구멍으로도 안 세어지고 backfill 대상도 아니다(backfill 은 커서부터 묻는다).\n */\n ...(firstUnseenBefore ? { firstUnseenBefore } : {})\n }\n}\n\n/**\n * 커서에 번호를 적는다 — **반영한 뒤에만.**\n *\n * 넣기 전에 올리면, 넣다가 실패했을 때 그 번호는 다시 오지 않는다. 보내는 쪽은 200 을 못 받았으니 다시\n * 보내겠지만, 그때는 커서가 이미 지나가 있어 `behind` 로 읽히고 버려진다.\n *\n * 적지 못하는 것은 사실 유입을 무르는 이유가 아니다 — 이미 들어간 사실은 그대로 두고, 다음 번호가 오면\n * `gap` 으로 드러난다. 그래서 실패를 던지지 않고 남긴다.\n */\nasync function saveSeq(\n store: HookStore,\n ref: { id: string; liveCursor?: unknown },\n scope: string,\n seq: number,\n firstSeq?: number\n): Promise<void> {\n const next = withSeq(ref.liveCursor, scope, seq, firstSeq)\n ref.liveCursor = next\n await store\n .saveCursor(ref.id, next)\n .catch(err => twinWarn(`[twin-hook] 번호를 커서에 적지 못했다 (${scope}=${seq}) — ${err?.message ?? err}`))\n}\n\n/**\n * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.\n *\n * 이 둘만 밖으로 낸다. 나머지는 인자만 보고 답하므로 시험이 데이터베이스를 세우지 않아도 된다.\n */\nexport interface HookStore {\n load(domainId: string, source: string): Promise<any | null>\n saveCursor(refId: string, cursor: unknown): Promise<void>\n}\n"]}
|
|
1
|
+
{"version":3,"file":"reference-hook.js","sourceRoot":"","sources":["../../../server/service/reference/reference-hook.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 연결된 시스템이 **밀어 주는** 사실을 받는 자리 — 웹훅.\n *\n * 규약(상태 코드 · 비밀값 · 대상 확인)은 `hook-contract.ts` 에 있다. 여기는 그것을 써서 찾고 · 확인하고 ·\n * 커넥터에게 옮기게 하고 · 유입으로 넘기는 순서만 맡는다.\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을\n * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로\n * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.\n *\n * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.\n *\n * ── 규약 ────────────────────────────────────────────────────────────────────\n *\n * 주소 POST /twin/hook/<연결이름>/<트윈> — no /domain/<도메인> prefix: the route sits on the domain-public\n * router without one (server/routes.ts:31); a prefixed address falls through and answers 405\n * 도메인 X-Things-Factory-Domain: <도메인> — the webhook module sends it from the destination's\n * params.receivingDomain\n * 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다\n * X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>\n * 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다\n * 응답 아래 §`hookStatus`\n *\n * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────\n * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서\n * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.\n *\n * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다\n * 훅을 못 쓰는 것이 낫습니다.\n *\n * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────\n * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,\n * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —\n * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로\n * 옮기면 약해지고 테스트가 없어집니다.\n *\n * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────\n * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서\n * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나\n * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.\n *\n * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────\n * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입\n * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지\n * 함께 알립니다.\n */\nimport { WEBHOOK_STATUS, type WebhookResponse } from '@operato/ops-contract'\n\nimport { twinWarn } from '../../engine/log.js'\n\nimport { getAdapter, type InboundBatch } from './reference-adapter.js'\nimport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nexport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nimport { authorizeHook, producedInstance, pushCursorKey, seqOf, takeInSequence, withSeq, type HookOutcome } from './hook-contract.js'\n\ntype WebhookLane = 'FACTS' | 'ATTENTIONS'\nfunction webhookLaneOf(value: unknown): WebhookLane | undefined {\n return value === undefined || value === 'FACTS' ? 'FACTS' : value === 'ATTENTIONS' ? 'ATTENTIONS' : undefined\n}\n\n/**\n * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.\n *\n * 유입 자체(`ingest`)는 부르는 쪽이 넘겨 준다: 이 파일이 엔진을 직접 부르면 시험할 때 엔진이 필요해지고,\n * 그러면 규약을 확인하는 시험을 쓸 수 없다.\n */\nexport async function handleHook(args: {\n domainId: string\n source: string\n instanceId: string\n headers: Record<string, unknown>\n body: unknown\n /**\n * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다.\n *\n * 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다. 없으면 서명을 쓰는\n * 요청은 거절된다(§`authorizeHook`).\n */\n rawBody?: string\n /** 서명 창을 재는 기준 시각. 부르는 쪽이 준다 — 여기서 읽으면 시험이 시계에 매인다. */\n nowMs?: number\n /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */\n ingest: (instanceId: string, records: unknown[], lane: WebhookLane) => IngestResult | Promise<IngestResult>\n /**\n * 구멍을 봤다 — **부르는 쪽이 무엇을 할지 정한다.**\n *\n * 여기서 backfill 을 직접 부르지 않는다. 이 파일은 `ingest`·`store` 를 인자로 받아 가볍게 유지한다\n * (그래야 테스트가 엔진 없이 이 판정을 확인할 수 있다). backfill 을 import 하면 그 규율이 깨진다.\n *\n * 기다리지 않는 것도 부르는 쪽의 몫이다 — 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.\n */\n onGap?: (scope: string) => void\n /**\n * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**\n *\n * `ingest` 를 부르는 쪽이 넘겨 주는 것과 같은 이유다(위 §). 커서는 재기동을 넘어 살아야 하는데, 한\n * 프로세스 안에서만 확인하면 「적히나」는 보이지만 「다시 세우면 읽히나」는 안 보인다. 그 둘이 갈린\n * 결함을 이 저장소가 이미 겪었다.\n */\n store: HookStore\n}): Promise<HookOutcome> {\n const { domainId, source, instanceId, headers, body, rawBody, ingest, onGap } = args\n const nowMs = args.nowMs ?? Date.now()\n const { store } = args\n\n const ref = await store.load(domainId, source)\n if (!ref) {\n return { status: WEBHOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection \"${source}\"` } }\n }\n\n const cfg: any = (ref as any).connectionConfig ?? {}\n const expected = String(cfg.hookSecret ?? '').trim()\n if (!expected) {\n /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */\n return {\n status: WEBHOOK_STATUS.badSecret,\n body: {\n ok: false,\n error: `connection \"${source}\" declares no hookSecret — set one in the connection settings before pushing to it`\n }\n }\n }\n const auth = authorizeHook({ headers, rawBody, secret: expected, nowMs })\n if (auth.ok === false) {\n return { status: WEBHOOK_STATUS.badSecret, body: { ok: false, error: auth.reason } }\n }\n\n const site = producedInstance(ref as any, instanceId)\n if (!site) {\n return {\n status: WEBHOOK_STATUS.unknownTarget,\n body: { ok: false, error: `twin \"${instanceId}\" was not created by connection \"${source}\"` }\n }\n }\n\n const adapter: any = getAdapter(String((ref as any).adapterType ?? ''))\n if (typeof adapter?.handleInbound !== 'function') {\n return {\n status: WEBHOOK_STATUS.unsupported,\n body: { ok: false, error: `connector \"${(ref as any).adapterType}\" cannot take pushed events (no handleInbound)` }\n }\n }\n\n let batch: InboundBatch\n try {\n batch = adapter.handleInbound(cfg, site, body, headers)\n } catch (e: any) {\n /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */\n return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } }\n }\n const items = batch?.items\n if (!Array.isArray(items)) {\n return {\n status: WEBHOOK_STATUS.badPayload,\n body: { ok: false, error: 'the connector did not return a list of items' }\n }\n }\n\n /*\n * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.\n * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.\n *\n * 판정은 `takeInSequence` 하나가 한다 — **backfill 하는 길도 같은 함수를 지난다.** 여기서 따로 만들면\n * 두 길이 다른 규칙으로 받고, 한쪽만 고쳐지는 날이 온다.\n */\n const lane = webhookLaneOf((batch as any).lane)\n if (!lane) {\n return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: 'unknown webhook lane' } }\n }\n const scope = typeof batch.scope === 'string' && batch.scope.trim() ? batch.scope.trim() : undefined\n /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */\n const key = scope ? pushCursorKey(instanceId, scope) : undefined\n const taken = takeInSequence({\n items,\n scope,\n lastSeq: key ? seqOf((ref as any).liveCursor, key) : undefined\n })\n if (taken.refused) {\n /* 반쯤 확인한 것을 확인했다고 말하지 않는다. */\n return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: taken.refused } }\n }\n const numbered = taken.numbered\n const gap = taken.gap\n /*\n * 첫 봉투가 1번이 아니면 **그 사실을 남긴다.** 커서가 없는 연결에 21번이 오면 커서가 21 로 뛰고,\n * 그 앞 스무 건은 구멍으로도 안 세어진다. 실제로 plant 에서 그렇게 스무 건이 조용히 사라졌다.\n *\n * 손실이라고 말하지 않는다 — 늦게 붙은 트윈은 그 앞을 안 받기로 한 것이다. 수만 말하고 판단은\n * 사람이 한다.\n */\n if (taken.firstUnseenBefore) {\n twinWarn(\n `[twin-ingest] \"${instanceId}\" 의 ${scope ?? '(단위 없음)'} 를 ${taken.advancedSeq} 번부터 받기 시작했습니다 — ` +\n `그 앞 ${taken.firstUnseenBefore}건은 받은 적이 없습니다. 원본이 오래 돌고 있었으면 정상이고, ` +\n `보냈는데 못 받은 것이면 그만큼이 빠진 것입니다`\n )\n }\n const advanced = taken.advancedSeq !== undefined && key ? { scope: key, seq: taken.advancedSeq } : undefined\n\n const records = taken.records\n\n if (!records.length) {\n /*\n * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터\n * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.\n */\n if (gap) {\n if (scope) onGap?.(scope)\n return gapOutcome(scope, gap)\n }\n if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n return {\n status: WEBHOOK_STATUS.ok,\n body: {\n ok: true,\n offered: 0,\n applied: 0,\n duplicates: 0,\n vocabulary: 0,\n rejected: [],\n ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n }\n }\n }\n\n let result: IngestResult\n try {\n result = await ingest(instanceId, records, lane)\n } catch (e: any) {\n return { status: WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }\n }\n const rejected = result.rejected ?? []\n /*\n * ── 떨어진 것에 **봉투 id** 를 붙인다 (2026-09-07 측정) ──────────────────────\n * 이 응답이 `{ record, errors }` 목록이었고, plant 은 그것을 **봉투 id 문자열 목록**으로 읽고\n * 있었다. `Array.isArray` 는 통과하므로 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도\n * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.**\n *\n * 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 · 오류 없음 · 보냈음이었다. 우리가 말했는데\n * 상대가 못 알아듣는 모양이면, 말한 것이 아니다.\n *\n * 그래서 봉투 id 를 함께 싣는다. 보내는 쪽이 자기 행을 표시할 수 있고 까닭도 남는다.\n *\n * **id 를 못 찾으면 레코드를 그대로 싣는다.** 그때는 무엇이 떨어졌는지 알 방법이 그것뿐이고,\n * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다.\n *\n * 짝은 **객체 동일성**으로 짓는다. `records` 는 `items` 의 순서와 원소를 그대로 들고 있고\n * (§`takeInSequence`), 그래서 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면\n * 같은 모양의 레코드 둘이 서로의 id 를 가져간다.\n */\n const forCaller = rejectedForCaller(rejected, items as { record?: unknown; eventId?: unknown }[])\n\n if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0 && !result.vocabulary) {\n /*\n * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.\n * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.\n *\n * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이\n * 뜬 뒤에 그 구간이 비어 있게 된다.\n *\n * ── Vocabulary is why this test needs a fourth term (2026-09-07) ──────────\n * This inference reads an absence as a cause, and one absence is legitimate: a batch that was\n * entirely vocabulary applies no events, has no duplicates and rejects nothing, and yet\n * everything in it landed (§`applyMasterData`). Without the last term the receiver answers\n * 503 to correct traffic, and the sender then holds those facts and retries every thirty\n * seconds for as long as they keep arriving — the reply invents a reason (\"not running live\")\n * that the numbers do not support.\n *\n * Found by a test written for the response sum, not by reading this line.\n *\n * ── Why this branch has to say something out loud ─────────────────────────\n * Measured today: a 503 from here leaves **no trace on either side.** The sender maps it to\n * backpressure and returns without touching `attempts` or `lastError`, and this branch logged\n * nothing, so a sender re-offering the same batch every thirty seconds is invisible to both.\n *\n * That is also why \"it has not happened\" could not be established: `attempts 0` on the seven\n * vocabulary envelopes was offered as evidence and is not evidence, because this path never\n * increments that counter. Telling a sender to come back forever is worth one line.\n */\n twinWarn(\n `[twin-hook] \"${instanceId}\" 에 ${records.length}건이 왔는데 한 건도 앉지 않아 ` +\n `${NOT_LIVE_RETRY_MS / 1000}초 뒤 다시 오라고 답했습니다 — 트윈이 실시간으로 돌지 않는 것으로 봅니다. ` +\n `보내는 쪽은 이 답에 재시도 횟수를 남기지 않으므로, 되풀이되면 이 줄만 늘어납니다`\n )\n\n return {\n status: WEBHOOK_STATUS.notLive,\n body: {\n ok: false,\n error: `twin \"${instanceId}\" is not running live — nothing was applied`,\n offered: records.length,\n retryAfterMs: NOT_LIVE_RETRY_MS\n }\n }\n }\n\n if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n\n /*\n * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게\n * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.\n */\n if (gap) {\n if (scope) onGap?.(scope)\n return gapOutcome(scope, gap, forCaller, advanced)\n }\n\n if (rejected.length) {\n /*\n * **다시 보내라고 하지 않는다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,\n * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다.\n */\n return {\n status: WEBHOOK_STATUS.partial,\n body: {\n ok: false,\n error: `${rejected.length} of ${records.length} records did not pass validation`,\n offered: records.length,\n applied: result.applied,\n duplicates: result.duplicates,\n vocabulary: result.vocabulary ?? 0,\n rejected: forCaller,\n ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n }\n }\n }\n\n return {\n status: WEBHOOK_STATUS.ok,\n body: {\n ok: true,\n offered: records.length,\n applied: result.applied,\n duplicates: result.duplicates,\n /*\n * Always reported, even as zero — the sender's sum has a term for it either way, and a field\n * that appears only sometimes makes an absent one indistinguishable from a receiver that\n * does not count vocabulary at all.\n */\n vocabulary: result.vocabulary ?? 0,\n rejected: [],\n ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n }\n }\n}\n\n/**\n * 유입이 돌려주는 것.\n *\n * 떨어진 것을 **수가 아니라 목록으로** 받는다. 수만 받으면 보내는 쪽에 「몇 건이 떨어졌다」밖에 말할 수\n * 없고, 그러면 무엇을 따로 두어야 할지 알 수 없어 배치 전체를 다시 보내거나 전부 버린다.\n */\nexport interface IngestResult {\n applied: number\n duplicates: number\n rejected: { record: unknown; errors: string[] }[]\n /**\n * How many records were vocabulary rather than events — **needed so the reply's sum closes.**\n *\n * `liveIngest` has counted this all along and this boundary dropped it, because the callback was\n * typed as `IngestResult` and vocabulary was not on it. So `offered` counted those records and\n * none of the other three did, and a sender checking the sum would have seen a loss on ordinary\n * traffic (§`WebhookResponse.offered`).\n *\n * Optional because an ingest that handles no vocabulary need not say zero, and a caller that\n * simply does not know must not be made to claim none.\n */\n vocabulary?: number\n}\n\n/**\n * 구멍을 알리는 응답 — **앞의 것은 받았다는 것을 함께 말한다.**\n *\n * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서\n * 처리량만 먹는다.\n */\n/*\n * 구멍을 본 자리에서 **바로 받는다** — 번호가 비었다는 것을 아는 가장 이른 순간이다.\n *\n * 기다리지 않는다. 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번\n * 온다. 그리고 같은 단위를 1분 안에 두 번 부르지 않는다(§`FILL_DEBOUNCE_MS`) — 밀어 받는 쪽이\n * 구멍 뒤의 봉투를 계속 보내면 그때마다 구멍 판정이 나기 때문이다.\n */\nfunction gapOutcome(\n scope: string | undefined,\n gap: { expectedSeq: number; lastSeq: number },\n /*\n * 떨어진 것 — 봉투 id 를 알면 그것을, 모르면 레코드를 싣는다(§`InboundItem.eventId`).\n * 보내는 쪽이 자기 행을 찾을 수 있어야 하고, 못 찾으면 무엇이 떨어졌는지라도 보여야 한다.\n */\n rejected: RejectedForCaller[] = [],\n advanced?: { scope: string; seq: number }\n): HookOutcome {\n return {\n status: WEBHOOK_STATUS.sequenceGap,\n body: {\n ok: false,\n error: 'sequence gap',\n scope,\n expectedSeq: gap.expectedSeq,\n lastSeq: advanced?.seq ?? gap.lastSeq,\n ...(rejected.length ? { rejected } : {})\n }\n }\n}\n\n/**\n * 트윈이 안 돌 때 얼마나 쉬라고 할 것인가.\n *\n * 사람이 트윈을 띄워야 풀리므로 초 단위로 다시 두드릴 이유가 없다. 그렇다고 길게 잡으면 트윈이 뜬 뒤\n * 그만큼 늦게 이어진다.\n */\nconst NOT_LIVE_RETRY_MS = 30_000\n\n/**\n * 응답에 번호를 어떻게 적나 — **확인한 것과 확인하지 않은 것을 구별한다.**\n *\n * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느\n * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.\n */\n/*\n * The return type is the contract's, narrowed to the fields this function fills.\n *\n * It was `Record<string, unknown>`, and because the result is **spread** into the reply, an index\n * signature slips past the excess-property check entirely — the four fields below were unverified\n * even after `HookOutcome.body` was typed. Naming them here is what makes the check reach them.\n */\nfunction seqBody(\n scope: string | undefined,\n advanced: { scope: string; seq: number } | undefined,\n numbered: boolean,\n firstUnseenBefore?: number\n): Pick<WebhookResponse, 'sequenceChecked' | 'scope' | 'lastSeq' | 'firstUnseenBefore'> {\n if (!numbered) return { sequenceChecked: false }\n return {\n sequenceChecked: true,\n scope,\n lastSeq: advanced?.seq,\n /*\n * 첫 봉투였고 그 앞을 못 봤으면 **그 수를 보내는 쪽에 돌려준다.** 안 돌려주면 그 사실이 아무 데도\n * 안 남는다 — 구멍으로도 안 세어지고 backfill 대상도 아니다(backfill 은 커서부터 묻는다).\n */\n ...(firstUnseenBefore ? { firstUnseenBefore } : {})\n }\n}\n\n/**\n * 커서에 번호를 적는다 — **반영한 뒤에만.**\n *\n * 넣기 전에 올리면, 넣다가 실패했을 때 그 번호는 다시 오지 않는다. 보내는 쪽은 200 을 못 받았으니 다시\n * 보내겠지만, 그때는 커서가 이미 지나가 있어 `behind` 로 읽히고 버려진다.\n *\n * 적지 못하는 것은 사실 유입을 무르는 이유가 아니다 — 이미 들어간 사실은 그대로 두고, 다음 번호가 오면\n * `gap` 으로 드러난다. 그래서 실패를 던지지 않고 남긴다.\n */\nasync function saveSeq(\n store: HookStore,\n ref: { id: string; liveCursor?: unknown },\n scope: string,\n seq: number,\n firstSeq?: number\n): Promise<void> {\n const next = withSeq(ref.liveCursor, scope, seq, firstSeq)\n ref.liveCursor = next\n await store\n .saveCursor(ref.id, next)\n .catch(err => twinWarn(`[twin-hook] 번호를 커서에 적지 못했다 (${scope}=${seq}) — ${err?.message ?? err}`))\n}\n\n/**\n * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.\n *\n * 이 둘만 밖으로 낸다. 나머지는 인자만 보고 답하므로 시험이 데이터베이스를 세우지 않아도 된다.\n */\nexport interface HookStore {\n load(domainId: string, source: string): Promise<any | null>\n saveCursor(refId: string, cursor: unknown): Promise<void>\n}\n"]}
|
package/package.json
CHANGED
|
@@ -1,7 +1,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@things-factory/headless-twin",
|
|
3
|
-
"version": "10.1.
|
|
3
|
+
"version": "10.1.150",
|
|
4
4
|
"main": "dist-server/index.js",
|
|
5
|
+
"exports": {
|
|
6
|
+
".": "./dist-server/index.js",
|
|
7
|
+
"./log": "./dist-server/engine/log.js",
|
|
8
|
+
"./*": "./*"
|
|
9
|
+
},
|
|
10
|
+
"typesVersions": {
|
|
11
|
+
"*": {
|
|
12
|
+
"log": [
|
|
13
|
+
"dist-server/engine/log.d.ts"
|
|
14
|
+
]
|
|
15
|
+
}
|
|
16
|
+
},
|
|
5
17
|
"things-factory": true,
|
|
6
18
|
"author": "heartyoh <heartyoh@hatiolab.com>",
|
|
7
19
|
"description": "Headless digital-twin host — operato-twin kernel(WMS/YMS/MES) 를 things-factory 모듈로 호스팅(State GraphQL subscription + 이벤트 영속 + 워커 tick + command/scenario mutation).",
|
|
@@ -29,11 +41,11 @@
|
|
|
29
41
|
"dependencies": {
|
|
30
42
|
"@operato/ops-contract": "^0.9.40",
|
|
31
43
|
"@operato/twin-kernel": "^0.11.29",
|
|
32
|
-
"@things-factory/auth-base": "^10.1.
|
|
33
|
-
"@things-factory/cache-service": "^10.1.
|
|
34
|
-
"@things-factory/env": "^10.1.
|
|
35
|
-
"@things-factory/ingest": "^10.1.
|
|
36
|
-
"@things-factory/shell": "^10.1.
|
|
44
|
+
"@things-factory/auth-base": "^10.1.150",
|
|
45
|
+
"@things-factory/cache-service": "^10.1.150",
|
|
46
|
+
"@things-factory/env": "^10.1.149",
|
|
47
|
+
"@things-factory/ingest": "^10.1.150",
|
|
48
|
+
"@things-factory/shell": "^10.1.150"
|
|
37
49
|
},
|
|
38
|
-
"gitHead": "
|
|
50
|
+
"gitHead": "39c135863f5f7455dcd80b8907550a1c91a86118"
|
|
39
51
|
}
|
|
@@ -13,7 +13,10 @@
|
|
|
13
13
|
*
|
|
14
14
|
* ── 규약 ────────────────────────────────────────────────────────────────────
|
|
15
15
|
*
|
|
16
|
-
* 주소 POST /
|
|
16
|
+
* 주소 POST /twin/hook/<연결이름>/<트윈> — no /domain/<도메인> prefix: the route sits on the domain-public
|
|
17
|
+
* router without one (server/routes.ts:31); a prefixed address falls through and answers 405
|
|
18
|
+
* 도메인 X-Things-Factory-Domain: <도메인> — the webhook module sends it from the destination's
|
|
19
|
+
* params.receivingDomain
|
|
17
20
|
* 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다
|
|
18
21
|
* X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>
|
|
19
22
|
* 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다
|
|
@@ -13,7 +13,10 @@
|
|
|
13
13
|
*
|
|
14
14
|
* ── 규약 ────────────────────────────────────────────────────────────────────
|
|
15
15
|
*
|
|
16
|
-
* 주소 POST /
|
|
16
|
+
* 주소 POST /twin/hook/<연결이름>/<트윈> — no /domain/<도메인> prefix: the route sits on the domain-public
|
|
17
|
+
* router without one (server/routes.ts:31); a prefixed address falls through and answers 405
|
|
18
|
+
* 도메인 X-Things-Factory-Domain: <도메인> — the webhook module sends it from the destination's
|
|
19
|
+
* params.receivingDomain
|
|
17
20
|
* 인증 연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다
|
|
18
21
|
* X-Twin-Hook-Secret: <비밀값> 또는 Authorization: Bearer <비밀값>
|
|
19
22
|
* 본문 연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* ★ The hook address the contract comments give is the address the route answers.
|
|
3
|
+
*
|
|
4
|
+
* 2026-10-11: both contract comments said `POST /domain/<도메인>/twin/hook/…`. The route sits on the
|
|
5
|
+
* domain-public router with no prefix, so the warehouse destination, written from that comment, got 405
|
|
6
|
+
* for every fact. The tenant travels in the X-Things-Factory-Domain header (the webhook destination's
|
|
7
|
+
* params.receivingDomain), not in the path.
|
|
8
|
+
*/
|
|
9
|
+
import { test } from 'node:test'
|
|
10
|
+
import assert from 'node:assert/strict'
|
|
11
|
+
import { readFileSync } from 'node:fs'
|
|
12
|
+
|
|
13
|
+
const read = (rel: string) => readFileSync(new URL(`../server/${rel}`, import.meta.url), 'utf8')
|
|
14
|
+
|
|
15
|
+
const route = read('routes.ts').match(/router\.post\('([^']*twin\/hook[^']*)'/)?.[1]
|
|
16
|
+
|
|
17
|
+
test('the hook route is registered without a domain prefix', () => {
|
|
18
|
+
assert.equal(route, '/twin/hook/:source/:instanceId')
|
|
19
|
+
})
|
|
20
|
+
|
|
21
|
+
for (const file of ['service/reference/hook-contract.ts', 'service/reference/reference-hook.ts']) {
|
|
22
|
+
test(`${file} gives the address the route answers`, () => {
|
|
23
|
+
const line = read(file).match(/주소\s+POST\s+(\S+)/)?.[1]
|
|
24
|
+
assert.ok(line, 'no address line')
|
|
25
|
+
assert.equal(line, '/twin/hook/<연결이름>/<트윈>')
|
|
26
|
+
assert.equal(line.replace(/<[^>]+>/g, 'x'), route!.replace(/:\w+/g, 'x'), 'the comment and the route name different paths')
|
|
27
|
+
})
|
|
28
|
+
}
|