Skip to content

docs(lfs): align gh-pages with PR #139 breaking changes#143

Merged
novatechflow merged 2 commits into
KafScale:gh-pagesfrom
kamir:docs/gh-pages-align-lfs-pr139
May 17, 2026
Merged

docs(lfs): align gh-pages with PR #139 breaking changes#143
novatechflow merged 2 commits into
KafScale:gh-pagesfrom
kamir:docs/gh-pages-align-lfs-pr139

Conversation

@kamir
Copy link
Copy Markdown
Collaborator

@kamir kamir commented May 16, 2026

Summary

Companion to KafScale/platform#139. Updates the three LFS docs on gh-pages so they reflect the breaking changes shipping in #139 — per @novatechflow's request to keep gh-pages in sync with main.

What changed

File Changes
_docs/lfs-proxy.md Env vars LFS_*KAFSCALE_LFS_PROXY_* (the actual names in cmd/proxy/lfs.go). Bucket example kafscalemy-bucket. Endpoint POST /v1/topics/{topic}/records → real POST /lfs/produce. New "Trust model and integrity verification" section documenting buffer-then-verify download, required integrity.sha256 + integrity.size on stream mode, presign opt-in (KAFSCALE_LFS_PROXY_PRESIGN_ENABLED), and all new error codes (integrity_failure, missing_integrity_size, payload_too_large, presign_disabled).
_docs/lfs-helm.md bucket: kafscalemy-bucket, with explanatory comment about the kafscale-lfs startup blocklist.
_docs/lfs-sdks.md Bucket example kafscalemy-bucket. Resolve() example annotated: SDK populates integrity claim from envelope; proxy verifies bytes before streaming. Trust-model callout linking to the LFS Proxy doc.

Test plan

  • bundle exec jekyll build succeeds (no broken internal links)
  • Page renders cleanly on the staging preview
  • All four new error codes (integrity_failure, missing_integrity_size, payload_too_large, presign_disabled) appear in the rendered error table
  • /lfs-proxy/#trust-model-and-integrity-verification anchor resolves from the _docs/lfs-sdks.md callout

Notes

🤖 Generated with Claude Code

PR KafScale#139 (`fix/s3-bucket-takeover-cve` on main) introduced breaking changes
to the LFS proxy. Documentation on gh-pages drifted; @novatechflow asked
that gh-pages be updated alongside main so users don't follow stale guides.

Changes to `_docs/lfs-proxy.md`:
  * Env var names: `LFS_*` → `KAFSCALE_LFS_PROXY_*` (the real names in
    cmd/proxy/lfs.go).
  * Replace `bucket: kafscale` example with `my-bucket` (the bucket name
    `kafscale-lfs` is permanently blocklisted at startup; using anything
    that looks like it invites future confusion).
  * Replace stale endpoint `POST /v1/topics/{topic}/records` with the real
    `POST /lfs/produce` (and pointer to the multipart upload endpoints).
  * New "Trust model and integrity verification" section documenting the
    buffer-then-verify download design, the required `integrity.sha256`
    AND `integrity.size` fields on stream mode, the `KAFSCALE_LFS_PROXY_
    PRESIGN_ENABLED` opt-in for presign mode, and the new error codes
    (`integrity_failure`, `missing_integrity_size`, `payload_too_large`,
    `presign_disabled`).
  * Quick-start curl example switched to `/lfs/produce`.

Changes to `_docs/lfs-helm.md`:
  * Same `bucket: kafscale` → `my-bucket` substitution with explanatory
    comment about the blocklist.

Changes to `_docs/lfs-sdks.md`:
  * S3 bucket example: `kafscale` → `my-bucket`.
  * Resolve() example annotated to clarify the SDK populates the integrity
    claim from the envelope, and the proxy verifies before streaming.
  * Trust-model callout with link to the LFS Proxy doc.

Companion to `KafScale#139`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@kamir
Copy link
Copy Markdown
Collaborator Author

kamir commented May 16, 2026

Pushed follow-up commit 3ae607f to remove the remaining docs drift.

What changed:

  • Updated the LFS envelope and object-key examples to match the current kfs_lfs/bucket/key/size/sha256 schema and default/topic/lfs/date/obj-* key shape.
  • Corrected the Go SDK example to use the actual NewProducer/Produce and NewS3Client/NewConsumer/Unwrap APIs.
  • Clarified that current SDK resolvers fetch directly from S3 with local checksum validation, while POST /lfs/download is the proxy-verified HTTP path.
  • Added the new invalid_integrity and temp_storage_failed download error docs.
  • Replaced stale presigned-download wording in the demos doc.

Verification:

  • git diff --check
  • rg check for stale API/schema terms in the touched LFS docs

@novatechflow novatechflow merged commit b435379 into KafScale:gh-pages May 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants