feat: add Dockerfile for tf-docs service + document keep-streaming decision

2026-09-02 14:40:48 +03:00
parent 4876f82f85
commit fe67511203
2 changed files with 58 additions and 0 deletions
@@ -82,3 +82,47 @@ TL;DR: docs (HTML/CSS/JS, обычно мелкие) стримятся чере
 **Further Considerations**
 1. Точное значение `STREAM_MAX_BYTES` и итоговый `S3_PUBLIC_BASE_URL` (path-style vs virtual-host style у Ceph RGW) — уточнить на этапе реализации/тестирования, не блокирует план.
 2. Нужен ли листинг версий/лендинг на tf_docs (как у registry `/v1/providers/*/versions`) — сейчас не включено в scope, можно добавить отдельным шагом при необходимости.
+
+---
+
+## Решение по вариантам реализации (2026-09-02, дополнение)
+
+Обнаружено, что `tf_docs/server.js` уже закоммичен (`4876f82 feat: add S3-backed documentation streaming service`) и использует `@aws-sdk/client-s3` (`GetObjectCommand` + `HeadBucketCommand`) — стримит весь контент через pod, без redirect. Зависимость `@aws-sdk/client-s3@3.879.0` уже в `package.json`.
+
+Рассматривались два варианта:
+
+1. **Redirect-версия** (по плану выше): мелкие HTML/CSS/JS стримить через pod, крупные/нестандартные файлы отдавать `302` на прямой публичный S3 URL; только stdlib Node.
+2. **AWS SDK-версия** (закоммиченная): стримить весь контент через pod.
+
+**Принято решение: оставить вариант 2, протестировать; перейти на вариант 1 только при реальных проблемах (таймауты/обрывы на крупных файлах).**
+
+Обоснование:
+
+- типовая документация MkDocs — мелкие HTML/CSS/JS, стриминг через pod не создаёт проблем;
+- вариант 2 позволяет держать бакет `docs/*` приватным (без public policy);
+- redirect нужен только при появлении крупных вложений (attachments/zip/pdf/видео).
+
+Критерии перехода на вариант 1:
+
+- крупный файл (pdf/zip > 2MB) через `/docs/...` обрывается или таймаутит;
+- деградация при параллельных запросах;
+- неприемлемая latency двойного hop (браузер → pod → S3).
+
+Прецедент для варианта 1: инцидент `/v1/proxy` для бинарников провайдера — стриминг ZIP через pod обрывался на ~20KB, заменён на HTTP 302 redirect (см. `tf_registry/HISTORY/incident-2026-09-01-proxy-s3-dns.md`).
+
+Redirect-версия (вариант 1) сгенерирована DeepSeek Flash, но **не записана** в `server.js`, чтобы не перезаписывать закоммиченный код. При переходе менять только `server.js`.
+
+**Dockerfile** — до этого отсутствовал, создан и скорректирован под вариант 2:
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY server.js ./
+ENV NODE_ENV=production
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+(установка зависимостей обязательна — иначе `@aws-sdk/client-s3` не найдётся в контейнере).