Skip to content

chore: remove dir_upload_public / dir_download_public surface (daemon + 15 SDKs + docs)#95

Merged
Nic-dorman merged 1 commit into
mainfrom
feat/v2-300-remove-dir-surface
May 19, 2026
Merged

chore: remove dir_upload_public / dir_download_public surface (daemon + 15 SDKs + docs)#95
Nic-dorman merged 1 commit into
mainfrom
feat/v2-300-remove-dir-surface

Conversation

@Nic-dorman
Copy link
Copy Markdown
Collaborator

Summary

`dir_upload_public` / `dir_download_public` is a daemon-fabricated surface with no upstream backing. Upstream `WithAutonomi/ant-client` v2 has no directory primitive in `ant-core/src/data/client/` — only `file_upload` / `file_download` and variants (`file_upload_with_mode`, `file_prepare_upload`, `file_prepare_upload_with_visibility`, `finalize_upload`, `file_download_with_progress`, `estimate_upload_cost`). The daemon's dir handler called `file_upload_with_mode` on a directory path, which fails with `HTTP 500 — encryption failed: I/O error: Is a directory (os error 21)` because the underlying primitive expects a file. The dir surface was never functional in v2; it was only latent because previous example stubs errored at `file_cost` first.

This PR removes the surface end-to-end. Mirror of the graph_entry removal precedent. If a consumer later needs native directory upload, file it as a real product feature with a defined chunking + manifest contract.

What changes (18 commits)

1. Daemon (`830d6e4`)

  • `antd/src/rest/files.rs` — drop `dir_upload_public` and `dir_download_public` handlers
  • `antd/src/rest/mod.rs` — drop `/v1/dirs/upload/public` and `/v1/dirs/download/public` route registrations
  • `antd/src/grpc/service.rs` — drop `dir_upload_public` + `dir_download_public` gRPC methods
  • `antd/proto/antd/v1/files.proto` — drop `DirUploadPublic` + `DirDownloadPublic` RPCs (shared message types stay)
  • `antd/src/types.rs` — drop `DirUploadPublicResponse` struct
  • `antd/openapi.yaml` — drop the two dir paths + `DirUploadPublicResponse` schema
  • `antd/README.md` — drop endpoint-table rows

2. SDK fan-out (15 per-SDK commits) — `antd-go`, `antd-py`, `antd-js`, `antd-rust`, `antd-cpp`, `antd-csharp`, `antd-java`, `antd-dart`, `antd-ruby`, `antd-php`, `antd-elixir`, `antd-lua`, `antd-zig`, `antd-kotlin`, `antd-swift`. Each drops:

  • The sync and async client methods (`dir_upload_public`, `dir_download_public`, async variants where present)
  • The gRPC client wrappers
  • Any dir-specific result models
  • The exercising unit tests (or test cases within larger files)
  • README rows describing the methods

3. MCP wrapper (`5b0c230`) — `antd-mcp/src/antd_mcp/server.py`: drop `is_directory` flag from `upload_file` / `download_file` MCP tools.

4. Docs (`9d2b513`) — quickstart-*.md for cpp/csharp/dart/elixir/java/kotlin/lua/php/python/ruby/rust/swift/zig + `llms.txt` + `llms-full.txt` cleaned of dir-upload examples and method-signature rows.

What does NOT change

  • Generated proto stubs (`_pb.rb`, `.pb.go`, `*_pb2_grpc.py`, etc.) — they'll clear on next proto regen. Same deferral pattern as the graph removal precedent. Nothing imports the dead generated types.
  • Shared proto messages (`UploadFileRequest`, `DownloadPublicRequest`, `DownloadResponse`) — used by file routes too, stay.
  • File upload/download surface — completely untouched. Consumers wanting to upload a directory can recurse over files client-side and use `file_upload_public` per file.
  • Examples — the canonical `04-files` examples were already file-only (separate prior fix); this PR doesn't re-touch them.

Why now

v1.0 ship target. Shipping v1.0 with a daemon route that 500s on the happy path + 15 SDKs that ship a method which 500s is bad. Removal is the right call until a real product spec emerges. `-285 / +0` on the daemon alone; full PR ~`-1500 lines` of dead code across the repo.

Test plan

  • `git grep -E "dir_upload|dir_download|dirUpload|dirDownload|DirUpload|DirDownload"` returns only generated proto stubs (acceptable, deferred) + one FFI README reference (out of scope, separate concern — FFI is a planned UniFFI binding to the `autonomi` Rust crate, not the daemon).

  • Per-SDK unit tests green where toolchain available locally: go, python, js, rust, csharp, java, dart, php (all 100% pass).

  • Daemon compiles clean (`cargo check`).

  • End-to-end dev2 sweep on a 5-PR integration branch (this PR + the four in-flight example/cleanup PRs):

    SDK Result SDK Result
    python ✅ 13s lua ✅ 11s
    go ✅ 11s zig ✅ 51s
    js ✅ 13s dart ✅ 19s
    rust ✅ 19s csharp ✅ 27s
    cpp ✅ 50s swift ✅ 159s
    ruby ✅ 12s java ✅ 78s
    php ✅ 11s kotlin ✅ 98s
    elixir ✅ 13s

    15/15 PASS against `ant dev start --enable-evm` running the canonical 5 examples (connect/data/chunks/files/private) per SDK.

  • Reviewer: re-run the sweep on a fresh devnet, or re-merge to confirm the merge state matches.

Out of scope

  • Implementing native directory upload as a real feature — separate product spec needed.
  • Proto-stub regen across SDKs — deferred per the graph_entry removal precedent. The generated dead types don't break anything; they'll clear on next regen.
  • The one FFI README reference to dir_upload — flagged in the subagent report; out of scope here since FFI is a different planned-API doc, not a daemon caller.

🤖 Generated with Claude Code

… + 15 SDKs + docs)

Resolved against origin/main (which now contains #91/#92/#93/#94/#96) using
dev2 integration HEAD aa94940 as the canonical post-merge state. Net of the
example-file overlap with #93/#94, V2-300 reduces to 99 files / 44+ / 1694-.
@Nic-dorman Nic-dorman force-pushed the feat/v2-300-remove-dir-surface branch from 9d2b513 to 6c05afa Compare May 19, 2026 10:09
@Nic-dorman Nic-dorman merged commit 3a34c34 into main May 19, 2026
3 checks passed
Nic-dorman added a commit that referenced this pull request May 21, 2026
…efresh MCP mapping

Three drifts surfaced by the v1.0 surface-area sweep:

1. llms-full.txt still documented POST /v1/dirs/upload/public and
   /v1/dirs/download/public. PR #95 removed the dir surface from the
   daemon + protos + every SDK + per-SDK READMEs but missed
   llms-full.txt's REST routes section. The phantom is now gone.

2. /v1/chunks/prepare and /v1/chunks/finalize were never documented.
   The daemon routes them (antd/src/rest/mod.rs), every SDK exposes
   them (prepare_chunk_upload / finalize_chunk_upload), and the
   external-signer examples use them, but they appeared in neither
   llms-full.txt's REST section nor antd/openapi.yaml. Both gaps are
   closed: llms-full.txt has full request/response shapes (including
   the already_stored:true no-payment-needed path), and openapi.yaml
   has matching PrepareChunkRequest / PrepareChunkResponse /
   FinalizeChunkRequest / FinalizeChunkResponse schemas.

3. The MCP tool mapping was stale for the upload_file / download_file
   rows after antd-mcp #127 added the private flag to both tools. The
   table now matches #127's actual signatures and explains how the
   address field round-trips between public and private branches.

4. Adds a new "External Signer SDK Methods" section between the
   per-SDK signature blocks and the MCP mapping. Cross-language
   reference for prepare_data_upload / prepare_upload /
   prepare_upload_public / prepare_chunk_upload and the matching
   finalize_* / finalize_merkle_upload / finalize_chunk_upload
   methods, with a table mapping each SDK method to its REST route
   and finalize counterpart. All 15 SDKs expose these.

EventService is out of scope: it still exists in proto + daemon +
docs, consistent with each other. Whether to remove it remains a
separate v1.0 decision.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nic-dorman added a commit that referenced this pull request May 21, 2026
…efresh MCP mapping

Three drifts surfaced by the v1.0 surface-area sweep:

1. llms-full.txt still documented POST /v1/dirs/upload/public and
   /v1/dirs/download/public. PR #95 removed the dir surface from the
   daemon + protos + every SDK + per-SDK READMEs but missed
   llms-full.txt's REST routes section. The phantom is now gone.

2. /v1/chunks/prepare and /v1/chunks/finalize were never documented.
   The daemon routes them (antd/src/rest/mod.rs), every SDK exposes
   them (prepare_chunk_upload / finalize_chunk_upload), and the
   external-signer examples use them, but they appeared in neither
   llms-full.txt's REST section nor antd/openapi.yaml. Both gaps are
   closed: llms-full.txt has full request/response shapes (including
   the already_stored:true no-payment-needed path), and openapi.yaml
   has matching PrepareChunkRequest / PrepareChunkResponse /
   FinalizeChunkRequest / FinalizeChunkResponse schemas.

3. The MCP tool mapping was stale for the upload_file / download_file
   rows after antd-mcp #127 added the private flag to both tools. The
   table now matches #127's actual signatures and explains how the
   address field round-trips between public and private branches.

4. Adds a new "External Signer SDK Methods" section between the
   per-SDK signature blocks and the MCP mapping. Cross-language
   reference for prepare_data_upload / prepare_upload /
   prepare_upload_public / prepare_chunk_upload and the matching
   finalize_* / finalize_merkle_upload / finalize_chunk_upload
   methods, with a table mapping each SDK method to its REST route
   and finalize counterpart. All 15 SDKs expose these.

EventService is out of scope: it still exists in proto + daemon +
docs, consistent with each other. Whether to remove it remains a
separate v1.0 decision.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nic-dorman added a commit that referenced this pull request May 21, 2026
…0 surface (#126)

Final docs pass landing alongside the put/get rename + private-file gap close.
After this PR, what we document matches what the daemon and every SDK actually expose.

What's in this PR:

Per-SDK READMEs (14 SDKs, antd-go's lives on its own PR):
- Files API tables now list both private (file_put / file_get) and public
  (file_put_public / file_get_public) entries. Private = caller-held DataMap
  (NOT stored on-network); public = DataMap stored on-network at the returned
  address.
- Return types corrected to DataPutResult / DataPutPublicResult /
  FilePutResult / FilePutPublicResult. PutResult is now annotated as
  chunk_put only.
- Quick Start snippets stop reading result.cost on DataPutPublicResult --
  the field no longer exists; the examples now print chunks_stored instead.
- Data + Files signatures show the payment_mode kwarg/parameter that all
  put and cost methods accept.
- Models tables list the new typed results.

llms-full.txt:
- All 15 per-SDK Method Signature blocks refreshed with payment_mode,
  correct return types, and the private file_put / file_get entries.
- New "External Signer SDK Methods" cross-language reference section
  covering prepare_data_upload / prepare_upload / prepare_upload_public /
  prepare_chunk_upload and the matching finalize_* / finalize_merkle_upload /
  finalize_chunk_upload methods.
- REST routes section: drops the /v1/dirs/upload/public and
  /v1/dirs/download/public phantom (the dir surface was removed in #95 but
  llms-full.txt was not refreshed at the time). Adds POST /v1/chunks/prepare
  and POST /v1/chunks/finalize with full request/response shapes.
- MCP tool mapping updated for #127 -- upload_file / download_file now show
  both public and private branches.

antd/openapi.yaml:
- Adds /v1/chunks/prepare and /v1/chunks/finalize with full schemas
  (PrepareChunkRequest / PrepareChunkResponse / FinalizeChunkRequest /
  FinalizeChunkResponse), closing the documented-by-the-daemon-but-not-by-
  openapi gap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nic-dorman added a commit that referenced this pull request May 21, 2026
Cuts v0.8.0 atop v0.7.1. Substantial breaking-change roll-up of the
put/get rename, the private-file PUT/GET gap close, and several minor
surface cleanups -- bundled here so the v1.0 cut can ship stable on top.

## Breaking (antd daemon)

- feat(antd)!: bind to 127.0.0.1 by default on REST and gRPC (#107).
  Previously bound 0.0.0.0; use --bind-rest / --bind-grpc to override.
- chore: remove dead graph_entry surface from antd proto + 5 SDKs (#92).
  GraphService and its 4 RPCs are gone; REST mounts dropped.
- chore: remove dir_upload_public / dir_download_public surface (#95).
  Use file_put_public on a directory path instead; the daemon recurses.
- feat(antd)!: normalize put/get convention + close private-file PUT and
  GET gaps (#115). Method renames across proto + REST + SDKs:
    data_put_private    -> data_put
    data_get_private    -> data_get
    file_upload_public  -> file_put_public
    file_download_public -> file_get_public
  New: file_put / file_get for the private file path (previously only
  the public variant existed). New typed results: DataPutResult,
  DataPutPublicResult, FilePutResult, FilePutPublicResult; PutResult
  is now annotated as chunk_put only.

## Additive

- feat(antd): honor payment_mode on gRPC put/cost paths and REST cost
  endpoints (#114). Optional kwarg threaded through every put/cost
  signature; empty/omitted maps to "auto" so older clients keep working.
- feat: external-signer public uploads + single-chunk prepare/finalize
  across 15 SDKs (#90).
- docs+spec: openapi.yaml refreshed for the v1.0 surface, including
  POST /v1/chunks/prepare and /v1/chunks/finalize for single-chunk
  external-signer publish (#126).

## SDK fan-out (PaymentMode + put/get convention, all 15)

#116 antd-go, #117 antd-py/ruby/elixir, #118 antd-rust, #119 antd-csharp,
#120 antd-java, #121 antd-swift, #122 antd-dart, #123 antd-kotlin,
#124 antd-cpp, #125 antd-js/php/zig/lua, #127 antd-mcp.

## SDK example + build fixes

- fix(antd-go): make 03-files example self-contained and runnable (#91)
- fix(examples): make 04-files runnable across cpp/rust/elixir/lua/php/ruby/zig (#93)
- fix(examples): runnable dart 04_files + java Example03Files; add java Example03Chunks (#94)
- feat: gRPC transport example for antd-py and antd-rust (#113)
- feat(antd-py): 07_external_signer example + ant-dev dispatcher entry (#98)
- feat(antd-js): 07-external-signer example + antd-py empty-payments fix (#99)
- feat(rust/go): 07-external-signer examples (#100)
- feat(antd-csharp): 07_external_signer example (#101)
- feat(antd-java): 07_external_signer example (#102)
- feat(antd-kotlin): 07_external_signer example (#103)
- feat(antd-dart): 07_external_signer example (#104)
- feat(antd-ruby): 07_external_signer example (#105)
- feat(antd-php): 07_external_signer example (#106)
- chore(antd-kotlin): drop stale GraphDescendant from local proto copy (#108)

## Docs / infra

- docs: external-signer flow reference + ABI + python smoke test (#97)
- docs: add SECURITY.md with threat model and disclosure policy (#109)
- docs!: refresh per-SDK READMEs + llms-full.txt + openapi.yaml for v1.0 surface (#126)
- ci: add Go lint + test + vuln scanning for antd-go (#112)
- ci: extend antd-rust to sibling-repo parity (fmt + clippy + audit + doc) (#111)
- ci: skip antd/openapi.yaml and llms-full.txt from triggering CI (#128)
- chore(scripts): add full-stack + integration sweep helpers (#96)
- fix(antd-rust): regenerate Cargo.lock to unbreak --locked CI (#110)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.

1 participant