Skip to content

docs(guides): add the transports guide - #567

Open
chopmob-cloud wants to merge 2 commits into
a2aproject:mainfrom
chopmob-cloud:docs/534-transports-guide
Open

chopmob-cloud wants to merge 2 commits into
a2aproject:mainfrom
chopmob-cloud:docs/534-transports-guide

Conversation

@chopmob-cloud

Copy link
Copy Markdown
Contributor

Serves #534 (part of #521). Adds docs/guides/transports.md and a Guides nav section.

What it covers

Section Crate Feature flag
Choosing a binding — —
JSON-RPC and REST a2a-server, a2a-client rustls-tls (default) / native-tls
gRPC a2a-grpc, a2a-pb (proto/a2a.proto) —
Serving several bindings from one handler one RequestHandler —
TLS a2a_server::tls rustls-tls (default) / native-tls
SLIMRPC a2a-slimrpc —

Snippets

Included from compiled files via pymdownx.snippets with check_paths: true:

  • examples/src/helloworld/server.rs:routers — existing region, JSON-RPC + REST + card router
  • examples/src/helloworld/server.rs:grpc — new marker around the a2a-grpc service
  • examples/src/helloworld_tls/server.rs:tls-config — new marker around the rustls HTTP/gRPC config

The one gap, stated plainly

SLIMRPC has no runnable example in this repository — only src/, a README.md, and tests/e2e.rs. Rather than invent a snippet, its section points at the crate README (which documents the target format and the ServiceParams identity keys) and the e2e test. That is the only place this falls short of "every snippet is included from a compiled file".

If you would prefer a real SLIMRPC example in examples/ and a snippet from it, say so and I will add one, but that is a larger change than a docs page and I did not want to guess at the intended example shape.

Verification

  • mkdocs build --strict — exit 0
  • Rendered site/guides/transports/index.html contains each snippet's code (jsonrpc_router, rest_router, A2aServiceServer, GrpcHandler, load_rustls_config, TlsIncoming); no --8<-- markers leaked
  • Negative control: pointing a snippet at examples/src/nope/missing.rs fails the build with SnippetMissingError — the gate is live, not decorative
  • cargo check -p examples — clean
  • cargo fmt -p examples --check — exit 0

Refs #534.

@chopmob-cloud
chopmob-cloud requested a review from a team as a code owner November 19, 2026 20:38
@chopmob-cloud
chopmob-cloud force-pushed the docs/534-transports-guide branch from cd58e92 to 4f0bddf Compare November 19, 2026 20:38
@codecov

codecov Bot commented Nov 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Serves a2aproject#534 (part of a2aproject#521). Covers choosing a binding, JSON-RPC and REST, gRPC,
serving several bindings from one handler, TLS, and SLIMRPC.

Every snippet is included from a compiled file through pymdownx.snippets with
check_paths on, so a broken include fails `mkdocs build --strict`. The gRPC and
TLS regions needed markers added to the examples; the JSON-RPC/REST snippet is
the existing `routers` region.

Each binding names the crate and its feature flag. The TLS section records the
rustls-tls (default) versus native-tls choice for a2a-server and a2a-client.

SLIMRPC has no runnable example in this repository, so its section points at the
crate README and its e2e test rather than inventing a snippet from nothing. That
is the one place the guide falls short of "every snippet from a compiled file",
and it is called out here and in the PR rather than papered over.

Verified: `mkdocs build --strict` passes and the rendered page contains each
snippet; pointing a snippet at a missing file fails the build with
SnippetMissingError (negative control). `cargo check -p examples` and
`cargo fmt -p examples --check` are clean.

Refs a2aproject#534

Signed-off-by: AlgoVoi <chopmob@gmail.com>
a2aproject/a2a-cli removed specification/SPEC.md in a2aproject#161, so the link in the
vendored README returns 404 and fails the docs link check.

The link is pre-existing and unrelated to the transports guide, but it fails the
same Docs workflow this branch touches, so it is fixed here rather than left red.
Point at the published a2a-cli documentation, which is where the command
reference now lives.

Signed-off-by: AlgoVoi <chopmob@gmail.com>

This branch has not been deployed

No deployments
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