Files
MikrotikManager/docs/mcp-bandwidth-native-permit.md
T

26 lines
5.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Strict native bandwidth transport
В `MikrotikClient` реализован строгий путь для общего bandwidth broker. Он проверяет одноразовый private permit последним синхронным действием перед созданием HTTP request, после mutation policy и `beforeDispatch`. Это ещё не socket-send hook: DNS/TLS/agent queueing следуют за проверкой.
## Выпуск и использование
Permit выпускается только внутри существующего `createBandwidthAdmission.dispatch()` после новых подтверждённых reserve и arm. Наружу экспортируется verifier `consumeBandwidthNativePermit`, функции выпуска нет. Permit живёт в private WeakMap, связан с зафиксированным `nativeClient`, точным body и original signal/deadline. Проверка также использует исходный monotonic budget. Копирование, JSON, другой клиент, body, path, signal, expiry и повторное использование не дают HTTP. При завершении fixed send permit отзывается, в том числе после ошибки.
Trusted broker создаёт client через `MikrotikClient.fromServer(server, {requireBandwidthPermit:true})` либо строгий конструктор. Затем передаёт этот **же объект** как `nativeClient` admission dependencies. Fixed `send(binding, body, scope, permit)` вызывает `client.post('/tool/bandwidth-test', body, timeout, scope.signal, beforeDispatch, permit)` или `bandwidthTest(params, scope.signal, beforeDispatch, permit)`. Request JSON не выбирает transport callback, client или permit.
Строгий client копирует и замораживает endpoint/credentials/API prefix при создании. Body копируется до async guards; accessors отвергаются без чтения. Проверяются как аргумент `path`, так и фактический `apiPath + path`, включая slash/dot/case/encoded aliases и malformed escape в несвязанном proxy prefix. Permit разрешает только канонический аргумент `/tool/bandwidth-test`. Пользовательский API prefix сохраняется: это не принудительное ограничение на `/rest`.
## Реальная приёмка
[Отчёт](mcp-bandwidth-native-permit-acceptance-20261026.json) содержит хеши source/log и границы доказательств:
- 18 unit/HTTP-групп, 6 настоящих localhost запросов: helper/direct, максимальный duration 2147483647, no-SQL при отказах, snapshots, path aliases, late expiry/abort и отсутствие переносимости/replay permit. Откат wall clock до mint не обновляет исходный monotonic budget, установленный до reserve/arm. Journal этого профиля явно тестовый.
- 22 actual PG-группы signed control source и restricted runtime role включают 7 новых PostgreSQL → admission → strict HTTP сценариев. Три настоящих HTTP POST. Direct/helper завершают durable terminal release; после arm COMMIT с намеренно потерянным ACK transport не вызывается. Wrong client/copy/changed body дают 0 POST, nonterminal — 1 POST; оба участника остаются `unknown_busy`.
- Полный speed-workflow, strict TypeScript, lint и backend build.
## Следующая обязательная интеграция
**Это staged strict path, а не включённая защита всех callers.** Legacy construction пока явно сохранён. Нельзя объявлять его наличие глобальной bandwidth-защитой, включать публичный speed-tool или менять pending coverage только по этим тестам.
Далее broker обязан создавать только strict clients, разрешать canonical identities через genuine source/registry, связывать реальный remote address/VRF/zone отдельно от credential provider, сохранять original REST/scheduler/MCP authority и весь speed history/after-ping/error workflow. Затем мигрировать все callers и активировать общую границу после operator enrollment и действительного quiescence/writer barrier. При неизвестном remote исходе занятость не освобождается автоматически. См. [caller matrix](mcp-speed-common-gate-design-20261026.md) и [оставшуюся работу](mcp-remaining-work-20261026.md).