modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: add cargo (crates.io) as a package registry type (#1207)

Browse source 
> **Update — 2026-06-01 (commit 1f3be53)**
>
> - **All @P4ST4S review feedback addressed** — positive-path hermetic
mock + live anchor against `rust-faf-mcp v0.3.1`; 5xx routed as
transient; doc comment qualified. See the [close-out
comment](https://github.com/modelcontextprotocol/registry/pull/1207#issuecomment-4589711057)
for the per-item breakdown.
> - **Runtime-model question RESOLVED** — `package-types.mdx` documents
cargo and MCPB as both first-class Rust MCP distribution paths (cargo
for source-distributed, MCPB for prebuilt-binary). The "Open question"
section below was the original draft framing; the doc now ships the
resolution.
> - **Cargo-specific gotcha discovered and documented** — crates.io
strips HTML comments during README rendering, unlike PyPI/NuGet.
`package-types.mdx` now spells this out so cargo authors don't ship
invisible mcp-name tokens (which is exactly what happened to
`rust-faf-mcp v0.3.0`; fixed in v0.3.1).
> - **Stale reference removed in this update** — the "Out of scope" line
mentioning `docs/guides/publishing/publish-cargo.md` pointed at a path
that doesn't exist. The canonical per-type doc is
`docs/modelcontextprotocol-io/package-types.mdx`; the Cargo section has
been added there directly.
> - **Two real-world Rust MCP servers queued for day-one register**:
`rust-faf-mcp v0.3.1` (live, end-to-end validated by the new live test)
and `perfetto-mcp-rs` ([@0xZOne](https://github.com/0xZOne) in #1055).
> - **Tests:** 19/19 cargo tests pass (16 existing + 2 hermetic + 1 live
anchor). `make validate` clean. `golangci-lint` 0 issues.

---

Adds support for `registryType: cargo` so Rust MCP servers published to
crates.io can be registered through the
documented validation flow rather than the MCPB binary-packaging
workaround. Closes #1055.

  ## Motivation and Context

#1055 noted that crates.io has ~1,800 MCP-related packages with no
direct path into the registry — only the MCPB
binary-packaging workaround. This PR adds first-class support for cargo
as a package registry type: schema +
API surface, validator, integration tests, and a documented example. The
publishing guide
(`docs/guides/publishing/publish-cargo.md`) follows on this branch once
the runtime-model direction in
  **Additional context** is settled.

  ## How Has This Been Tested?

- **`make validate`** — clean. Schema-vs-openapi sync verified; 17/17
examples in `generic-server-json.md`
validate against the schema; `expectedServerJSONCount` bumped 16 → 17 to
match the new Cargo example.
- **`go test ./internal/validators/...`** — passes. 16 cargo validator
sub-cases across 4 test functions, run
  against real crates.io (~2.5s wall):
    - Input validation rejection paths
- Registry-baseURL rejection (4 variants: different host, trailing
slash, http-not-https, subdomain typo)
- Ownership validation against real crates (`serde`, `tokio`, `rand`) —
all correctly rejected for missing
  `mcp-name` token
- Server-name format variations (canonical `io.github.OWNER/REPO`,
multi-hyphen, underscore, numeric suffix)
- **Positive-path test** — gated on `rust-faf-mcp` v0.2.3+ being
published with `mcp-name:
io.github.Wolfe-Jam/rust-faf-mcp` in its README. Reserved as a TODO in
`cargo_test.go`; uncomments to become the
   live anchor once that publish lands.
- **Local `make test-unit`** — not run due to a Go toolchain version
quirk on my workstation (project
auto-downloads 1.26.0; my local `go` is 1.25.6, causing compile
mismatch). CI will exercise the full
  PostgreSQL-backed suite.

  ## Breaking Changes

None. This is an additive change — `cargo` joins the supported
`registryType` enum alongside
`npm`/`pypi`/`nuget`/`oci`/`mcpb`. Existing publishes continue to work
unchanged.

  ## Types of changes

  - [x] New feature (non-breaking change which adds functionality)
- [x] Documentation update (new Cargo example in
`generic-server-json.md`)

  ## Checklist

- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
  - [x] My code follows the repository's style guidelines
  - [x] New and existing tests pass locally
  - [x] I have added appropriate error handling
  - [x] I have added or updated documentation as needed

  ## Additional context

  ### Validator design — two-call retrieval on the documented API

`internal/validators/registries/cargo.go` mirrors the PyPI validator's
README-token approach (substring-match
`mcp-name: <serverName>`), with a two-call retrieval pattern to stay on
the documented public crates.io API:

1. `GET /api/v1/crates/{name}/{version}/readme` returns 200 OK with a
JSON pointer (`{"url":
"https://static.crates.io/readmes/.../...html"}`) — crates.io hands us
the URL rather than emitting a 302.
2. Follow the pointer to the rendered HTML; substring-match for the
token.

The two-call pattern stays on the documented public surface. The CDN URL
layout is observed-stable, but treating
it as the entry point would mean depending on an undocumented path. With
two calls, crates.io controls where
the README lives — if they move it, the metadata endpoint hands us the
new URL.

Missing crates and missing versions surface as **403** from the CDN
(S3's default for missing keys), not 404.
The validator treats any non-200 as "not found" and surfaces the actual
status code in the error message.

  ### Open question — runtime model

Cargo's runtime model is genuinely different from npm/PyPI/NuGet. `cargo
install` is one-time (binary lands on
PATH at `~/.cargo/bin`), not per-invocation like `npx`, `uvx`, or `dnx`
(the new one in .NET 10 SDK Preview 6+).
The new Cargo example in `generic-server-json.md` annotates this
honestly and omits `runtimeHint`.

If a different framing is preferred — e.g. recommending **MCPB**
(prebuilt binary distribution via GitHub
Releases) as the primary path for Rust MCP servers instead of cargo —
happy to adjust the documentation
accordingly. The schema + validator code in this PR is **additive** and
doesn't force a recommendation either
way; a Rust author who chooses cargo can use it, and one who prefers
MCPB still can.

  ### Out of scope (deferred)

- **`docs/guides/publishing/publish-cargo.md`** — follows on this branch
once the runtime-model direction above
  is settled.
- **Publisher CLI `Cargo.toml` autodetect** in
`cmd/publisher/commands/init.go` — separate concern, separate PR.
- **Positive-path validator test** — gated on `rust-faf-mcp` v0.2.3+
publishing as noted in *How Has This Been
  Tested?*.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Radoslav Dimitrov <radoslav@stacklok.com>
This commit is contained in:
Wolfe-James 2026-06-03 10:56:43 -04:00 • committed by GitHub
commit 685e354b2f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 671 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

2
internal/validators/package.go
View file

@ -23,6 +23,8 @@ func ValidatePackage(ctx context.Context, pkg model.Package, serverName string)
return registries.ValidateOCI(ctx, pkg, serverName)
case model.RegistryTypeMCPB:
return registries.ValidateMCPB(ctx, pkg, serverName)
case model.RegistryTypeCargo:
return registries.ValidateCargo(ctx, pkg, serverName)
default:
return fmt.Errorf("unsupported registry type: %s", pkg.RegistryType)
}

160
internal/validators/registries/cargo.go Normal file
View file

@ -0,0 +1,160 @@
package registries
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
"github.com/modelcontextprotocol/registry/pkg/model"
)
var (
ErrMissingIdentifierForCargo = errors.New("package identifier is required for Cargo packages")
ErrMissingVersionForCargo = errors.New("package version is required for Cargo packages")
)
// CargoReadmeMetaResponse is the structure returned by the crates.io readme metadata endpoint.
//
// With `Accept: application/json`, crates.io's /api/v1/crates/{name}/{version}/readme
// endpoint returns 200 OK with a JSON body containing a `url` field that points to the
// rendered README on the static CDN. (Without the Accept header, or via HEAD, the same
// endpoint emits a 302 redirect to the CDN URL — the validator uses the JSON path so
// that crates.io controls where the README lives.) Validators must follow the pointer
// to retrieve the actual README content.
type CargoReadmeMetaResponse struct {
URL string `json:"url"`
}
// ValidateCargo validates that a Cargo (crates.io) package contains the correct MCP server name.
//
// Verification mechanism: the `mcp-name: <server-name>` token is searched for in the package's
// rendered README. This mirrors the PyPI validator's README-token approach (see ValidatePyPI),
// requiring no Cargo.toml parsing on the registry side. Crate authors add a single line
// `mcp-name: io.github.OWNER/REPO` to their README before publishing.
//
// Two-call retrieval pattern:
// 1. GET https://crates.io/api/v1/crates/{name}/{version}/readme
// → 200 OK with JSON: {"url": "https://static.crates.io/readmes/.../...html"}
// 2. GET <url from step 1>
// → 200 OK with rendered README HTML, or 403 if the crate/version is missing
//
// The two-call pattern stays on the documented crates.io API surface rather than relying
// on the CDN URL layout being stable.
func ValidateCargo(ctx context.Context, pkg model.Package, serverName string) error {
// Set default registry base URL if empty
if pkg.RegistryBaseURL == "" {
pkg.RegistryBaseURL = model.RegistryURLCrates
}
if pkg.Identifier == "" {
return ErrMissingIdentifierForCargo
}
if pkg.Version == "" {
return ErrMissingVersionForCargo
}
// Validate that MCPB-specific fields are not present
if pkg.FileSHA256 != "" {
return fmt.Errorf("cargo packages must not have 'fileSha256' field - this is only for MCPB packages")
}
// Validate that the registry base URL matches crates.io exactly
if pkg.RegistryBaseURL != model.RegistryURLCrates {
return fmt.Errorf("registry type and base URL do not match: '%s' is not valid for registry type '%s'. Expected: %s",
pkg.RegistryBaseURL, model.RegistryTypeCargo, model.RegistryURLCrates)
}
return validateCargoREADME(ctx, pkg, serverName)
}
// validateCargoREADME performs the two-call README fetch and the mcp-name token
// check. It is split out from ValidateCargo so that httptest-based tests can
// drive the HTTP pipeline against a mock server (exposed via export_test.go),
// bypassing the exact-baseURL guard that ValidateCargo enforces for callers.
func validateCargoREADME(ctx context.Context, pkg model.Package, serverName string) error {
client := &http.Client{Timeout: 10 * time.Second}
// crates.io's crawler policy expects a non-generic User-Agent identifying the source.
userAgent := "MCP-Registry-Validator/1.0 (https://registry.modelcontextprotocol.io)"
// Step 1: fetch the README pointer from the documented API endpoint.
metaURL := fmt.Sprintf("%s/api/v1/crates/%s/%s/readme",
pkg.RegistryBaseURL,
url.PathEscape(pkg.Identifier),
url.PathEscape(pkg.Version))
metaReq, err := http.NewRequestWithContext(ctx, http.MethodGet, metaURL, nil)
if err != nil {
return fmt.Errorf("failed to create crates.io metadata request: %w", err)
}
metaReq.Header.Set("User-Agent", userAgent)
metaReq.Header.Set("Accept", "application/json")
metaResp, err := client.Do(metaReq)
if err != nil {
return fmt.Errorf("failed to fetch package metadata from crates.io: %w", err)
}
defer metaResp.Body.Close()
if metaResp.StatusCode != http.StatusOK {
// 5xx from the metadata endpoint is upstream availability, not a missing crate.
if metaResp.StatusCode >= 500 && metaResp.StatusCode < 600 {
return fmt.Errorf("crates.io upstream error fetching metadata for cargo package '%s' (status: %d) — likely transient, retry later", pkg.Identifier, metaResp.StatusCode)
}
return fmt.Errorf("cargo package '%s' metadata fetch failed (status: %d)", pkg.Identifier, metaResp.StatusCode)
}
var meta CargoReadmeMetaResponse
if err := json.NewDecoder(metaResp.Body).Decode(&meta); err != nil {
return fmt.Errorf("failed to parse crates.io readme metadata: %w", err)
}
if meta.URL == "" {
return fmt.Errorf("cargo package '%s' metadata response missing 'url' field", pkg.Identifier)
}
// Step 2: fetch the rendered README from the URL the API gave us.
readmeReq, err := http.NewRequestWithContext(ctx, http.MethodGet, meta.URL, nil)
if err != nil {
return fmt.Errorf("failed to create crates.io readme request: %w", err)
}
readmeReq.Header.Set("User-Agent", userAgent)
readmeReq.Header.Set("Accept", "text/html")
readmeResp, err := client.Do(readmeReq)
if err != nil {
return fmt.Errorf("failed to fetch rendered README from crates.io: %w", err)
}
defer readmeResp.Body.Close()
// Missing crates and missing versions surface as 403 from static.crates.io
// (S3's default for missing keys), not 404. 5xx from the CDN is upstream
// availability — surface it as transient so callers can distinguish retryable
// failures from genuinely missing crates.
if readmeResp.StatusCode != http.StatusOK {
if readmeResp.StatusCode >= 500 && readmeResp.StatusCode < 600 {
return fmt.Errorf("crates.io upstream error fetching README for cargo package '%s' version '%s' (status: %d) — likely transient, retry later", pkg.Identifier, pkg.Version, readmeResp.StatusCode)
}
return fmt.Errorf("cargo package '%s' version '%s' not found on crates.io (status: %d)", pkg.Identifier, pkg.Version, readmeResp.StatusCode)
}
body, err := io.ReadAll(readmeResp.Body)
if err != nil {
return fmt.Errorf("failed to read rendered README: %w", err)
}
// Search for the mcp-name: <server-name> token. The token contains no characters
// that get HTML-escaped during README rendering (no <, >, &, ", '), so a direct
// substring match against the rendered HTML is reliable.
mcpNamePattern := "mcp-name: " + serverName
if strings.Contains(string(body), mcpNamePattern) {
return nil
}
return fmt.Errorf("cargo package '%s' ownership validation failed. The server name '%s' must appear as 'mcp-name: %s' in the package README", pkg.Identifier, serverName, serverName)
}

411
internal/validators/registries/cargo_test.go Normal file
View file

@ -0,0 +1,411 @@
package registries_test
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"net/url"
"strings"
"sync/atomic"
"testing"
"github.com/modelcontextprotocol/registry/internal/validators/registries"
"github.com/modelcontextprotocol/registry/pkg/model"
"github.com/stretchr/testify/assert"
)
func TestValidateCargo_RealPackages(t *testing.T) {
ctx := context.Background()
tests := []struct {
name string
packageName string
version string
serverName string
expectError bool
errorMessage string
}{
{
name: "empty package identifier should fail",
packageName: "",
version: "0.1.0",
serverName: "io.github.example/test",
expectError: true,
errorMessage: "package identifier is required for Cargo packages",
},
{
name: "empty package version should fail",
packageName: "rust-faf-mcp",
version: "",
serverName: "io.github.example/test",
expectError: true,
errorMessage: "package version is required for Cargo packages",
},
{
name: "non-existent crate should fail",
packageName: generateRandomPackageName(),
version: "0.1.0",
serverName: "io.github.example/test",
expectError: true,
errorMessage: "not found",
},
{
name: "non-existent version of real crate should fail",
packageName: "serde",
version: "99.99.99-not-real",
serverName: "io.github.example/test",
expectError: true,
errorMessage: "not found",
},
{
name: "real crate without mcp-name token should fail",
packageName: "serde", // most-downloaded crate; no MCP server claim
version: "1.0.219",
serverName: "io.github.example/test",
expectError: true,
errorMessage: "ownership validation failed",
},
{
name: "real crate with mismatched mcp-name should fail",
packageName: "tokio",
version: "1.40.0",
serverName: "io.github.example/completely-different-name",
expectError: true,
errorMessage: "ownership validation failed",
},
{
name: "additional real crate without mcp-name (rand)",
packageName: "rand",
version: "0.9.0",
serverName: "io.github.example/test",
expectError: true,
errorMessage: "ownership validation failed",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
Identifier: tt.packageName,
Version: tt.version,
}
err := registries.ValidateCargo(ctx, pkg, tt.serverName)
if tt.expectError {
assert.Error(t, err)
assert.Contains(t, err.Error(), tt.errorMessage)
} else {
assert.NoError(t, err)
}
})
}
}
func TestValidateCargo_RegistryBaseURLMismatch(t *testing.T) {
ctx := context.Background()
tests := []struct {
name string
baseURL string
}{
{name: "different host", baseURL: "https://example.com"},
{name: "trailing slash", baseURL: "https://crates.io/"},
{name: "http (not https)", baseURL: "http://crates.io"},
{name: "subdomain", baseURL: "https://www.crates.io"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
RegistryBaseURL: tt.baseURL,
Identifier: "rust-faf-mcp",
Version: "0.2.2",
}
err := registries.ValidateCargo(ctx, pkg, "io.github.Wolfe-Jam/rust-faf-mcp")
assert.Error(t, err)
assert.Contains(t, err.Error(), "registry type and base URL do not match")
})
}
}
func TestValidateCargo_RejectsMCPBOnlyFields(t *testing.T) {
ctx := context.Background()
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
Identifier: "rust-faf-mcp",
Version: "0.2.2",
FileSHA256: "0000000000000000000000000000000000000000000000000000000000000000",
}
err := registries.ValidateCargo(ctx, pkg, "io.github.Wolfe-Jam/rust-faf-mcp")
assert.Error(t, err)
assert.Contains(t, err.Error(), "cargo packages must not have 'fileSha256' field")
}
// Server names follow io.github.OWNER/REPO and may contain dots, slashes,
// hyphens, underscores, and digits. None of these get HTML-escaped during
// README rendering, so substring match against the rendered HTML is reliable.
// These tests exercise format variations against a real crate that doesn't
// declare any mcp-name (serde) — every case fails ownership, but we verify
// the failure error preserves the exact server name unchanged.
func TestValidateCargo_ServerNameFormats(t *testing.T) {
ctx := context.Background()
tests := []struct {
name string
serverName string
}{
{name: "canonical io.github format", serverName: "io.github.Wolfe-Jam/rust-faf-mcp"},
{name: "multiple hyphens", serverName: "io.github.example/multi-hyphen-test-name"},
{name: "underscore", serverName: "io.github.example/snake_case_name"},
{name: "numeric suffix", serverName: "io.github.example/server-v2"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
Identifier: "serde",
Version: "1.0.219",
}
err := registries.ValidateCargo(ctx, pkg, tt.serverName)
assert.Error(t, err)
assert.Contains(t, err.Error(), tt.serverName)
})
}
}
// TestValidateCargo_PositivePathMock exercises the success branch: a README
// that contains the exact mcp-name token must return no error. Uses httptest
// to stand in for crates.io, so the test is hermetic — it doesn't depend on
// any live crate publishing a specific mcp-name line or on network reachability.
// Calls the test-only ValidateCargoREADME shim so the mock URL can take the
// place of https://crates.io without tripping the exact-baseURL guard.
func TestValidateCargo_PositivePathMock(t *testing.T) {
ctx := context.Background()
const serverName = "io.github.test/positive-path"
var mock *httptest.Server
mock = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if strings.HasSuffix(r.URL.Path, "/readme") {
w.Header().Set("Content-Type", "application/json")
if err := json.NewEncoder(w).Encode(map[string]string{
"url": mock.URL + "/static-readme",
}); err != nil {
t.Fatalf("encode meta response: %v", err)
}
return
}
// Rendered README HTML containing the mcp-name token.
fmt.Fprintf(w, "<html><body><p>some content</p><p>mcp-name: %s</p></body></html>", serverName)
}))
defer mock.Close()
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
RegistryBaseURL: mock.URL,
Identifier: "test-crate",
Version: "0.1.0",
}
err := registries.ValidateCargoREADME(ctx, pkg, serverName)
assert.NoError(t, err, "validator should accept a README containing the exact mcp-name token")
}
// TestValidateCargo_LivePositivePath is the live anchor — it validates against
// rust-faf-mcp v0.3.1 on real crates.io, the first crate published with the
// mcp-name token as visible markdown (v0.3.0 used a hidden HTML comment, which
// crates.io strips during README rendering — see package-types.mdx for the
// cargo-specific gotcha). Complements TestValidateCargo_PositivePathMock:
// the mock proves the validator works in principle (hermetic, fast); the live
// anchor proves it works against the real crates.io API + static CDN pipeline.
//
// If this test ever starts failing, check (in order):
// 1. Has rust-faf-mcp v0.3.1 been yanked or replaced?
// 2. Did crates.io change its README rendering pipeline (e.g., start
// stripping markdown lines that look like email-like tokens)?
// 3. Is the test machine network-blocked from crates.io or static.crates.io?
func TestValidateCargo_LivePositivePath(t *testing.T) {
ctx := context.Background()
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
Identifier: "rust-faf-mcp",
Version: "0.3.1",
}
err := registries.ValidateCargo(ctx, pkg, "io.github.Wolfe-Jam/rust-faf-mcp")
assert.NoError(t, err, "validator should accept the live rust-faf-mcp v0.3.1 crate (the canonical live anchor for cargo positive-path)")
}
// TestValidateCargo_TransientUpstreamError exercises the 5xx-as-transient branch:
// a 502/503 from static.crates.io is upstream availability, not "crate missing",
// and the error message must signal a retryable failure rather than imply the
// crate doesn't exist (the previous behavior, flagged in PR #1207 review).
func TestValidateCargo_TransientUpstreamError(t *testing.T) {
ctx := context.Background()
var mock *httptest.Server
mock = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if strings.HasSuffix(r.URL.Path, "/readme") {
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]string{
"url": mock.URL + "/static-readme",
})
return
}
// Simulate static.crates.io 502 — upstream blip, not a missing crate.
http.Error(w, "bad gateway", http.StatusBadGateway)
}))
defer mock.Close()
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
RegistryBaseURL: mock.URL,
Identifier: "test-crate",
Version: "0.1.0",
}
err := registries.ValidateCargoREADME(ctx, pkg, "io.github.test/transient")
assert.Error(t, err)
assert.Contains(t, err.Error(), "transient")
assert.NotContains(t, err.Error(), "not found", "transient upstream errors should not be reported as 'not found'")
}
// TestValidateCargoCombinedFixture exercises path-encoding and the full status
// matrix in one httptest fixture — the same pattern praised by @P4ST4S on
// PR #1321 for Go modules. One server dispatches on the crate identifier
// embedded in the URL path; wrong encoding routes to the fallback 500, which
// breaks the appropriate assertion. The explicit path assertion (assert.Equal
// on lastMetaPath) also catches encoding regressions directly.
func TestValidateCargoCombinedFixture(t *testing.T) {
ctx := context.Background()
const serverName = "io.github.test/combined"
tests := []struct {
name string
crateName string
version string
metaStatus int
readmeStatus int
readmeBody string
wantErr bool
wantContains []string
wantNotContains []string
}{
{
name: "happy_path_visible_token",
crateName: "combined-happy",
version: "0.1.0",
metaStatus: http.StatusOK,
readmeStatus: http.StatusOK,
readmeBody: fmt.Sprintf("<html><body><p>mcp-name: %s</p></body></html>", serverName),
},
{
name: "metadata_404",
crateName: "combined-meta404",
version: "0.1.0",
metaStatus: http.StatusNotFound,
wantErr: true,
wantContains: []string{"metadata fetch failed", "status: 404"},
},
{
name: "readme_403_s3_not_found",
crateName: "combined-readme403",
version: "0.1.0",
metaStatus: http.StatusOK,
readmeStatus: http.StatusForbidden,
wantErr: true,
wantContains: []string{"not found", "status: 403"},
},
{
name: "readme_502_transient",
crateName: "combined-readme502",
version: "0.1.0",
metaStatus: http.StatusOK,
readmeStatus: http.StatusBadGateway,
wantErr: true,
wantContains: []string{"transient"},
wantNotContains: []string{"not found"},
},
}
// lastMetaPath captures the metadata request path seen by the handler so
// each sub-test can assert the exact url.PathEscape-encoded form.
var lastMetaPath atomic.Value
lastMetaPath.Store("")
var srv *httptest.Server
srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
for i := range tests {
tt := &tests[i]
metaPath := fmt.Sprintf("/api/v1/crates/%s/%s/readme",
url.PathEscape(tt.crateName), url.PathEscape(tt.version))
staticPath := "/readme-static/" + url.PathEscape(tt.crateName)
if r.URL.Path == metaPath {
lastMetaPath.Store(r.URL.Path)
if tt.metaStatus != http.StatusOK {
http.Error(w, "simulated non-200", tt.metaStatus)
return
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]string{"url": srv.URL + staticPath})
return
}
if r.URL.Path == staticPath {
if tt.readmeStatus != http.StatusOK {
http.Error(w, "simulated non-200", tt.readmeStatus)
return
}
fmt.Fprint(w, tt.readmeBody)
return
}
}
http.Error(w, "unexpected path: "+r.URL.Path, http.StatusInternalServerError)
}))
defer srv.Close()
for i := range tests {
tt := tests[i]
lastMetaPath.Store("")
t.Run(tt.name, func(t *testing.T) {
wantMetaPath := fmt.Sprintf("/api/v1/crates/%s/%s/readme",
url.PathEscape(tt.crateName), url.PathEscape(tt.version))
pkg := model.Package{
RegistryType: model.RegistryTypeCargo,
RegistryBaseURL: srv.URL,
Identifier: tt.crateName,
Version: tt.version,
}
err := registries.ValidateCargoREADME(ctx, pkg, serverName)
// Assert encode step: the validator must have requested exactly the
// url.PathEscape-encoded path; wrong encoding hits the fallback 500.
assert.Equal(t, wantMetaPath, lastMetaPath.Load().(string),
"meta request path must be exactly the url.PathEscape-encoded form")
if tt.wantErr {
assert.Error(t, err)
for _, want := range tt.wantContains {
assert.Contains(t, err.Error(), want)
}
for _, notWant := range tt.wantNotContains {
assert.NotContains(t, err.Error(), notWant)
}
} else {
assert.NoError(t, err)
}
})
}
}

9
internal/validators/registries/export_test.go Normal file
View file

@ -0,0 +1,9 @@
package registries
// ValidateCargoREADME exposes the package-private validateCargoREADME to the
// external _test package so httptest-driven tests can exercise the README-fetch
// and mcp-name token-match pipeline against a mock server, bypassing the
// exact-baseURL guard that the public ValidateCargo enforces.
//
// Intended for cargo_test.go's positive-path and transient-error tests only.
var ValidateCargoREADME = validateCargoREADME