lablup / lablup/mlxcel

docs(server): document that --api-prefix removes the health endpoints from the public set

Open Beginner friendly
#1,671 0 comments 0 reactions 0 assignees View on GitHub
priority:low status:ready type:docs
Dominant language
Rust
Stars
467
Forks
54
Avg merge
4h 25m
Merged PRs (30d)
310

Description

## Summary

Setting `--api-prefix` silently makes the health endpoints require an API key, and the docs never mention it. The public-endpoint set is matched literally, so `/health` is not public. The server warns about this at runtime, but a reader of `docs/server-features.md` cannot learn it.

## Background

`is_public_endpoint` matches only the literal paths `"/"`, `"/health"`, and `"/v1/health"`, against the request path as the client sent it (prefix included). With `--api-prefix` set, the prefixed health paths no longer match, so they require a bearer key. A source comment states this, and `cli_input.rs` emits a runtime `tracing::warn!` when both are configured, but the docs describe the two features six lines apart with no cross-reference.

## Proposed Solution

Add 2-3 sentences to the "Transport and access control" section of `docs/server-features.md` connecting the two facts: with keys enabled the public set is `/`, `/health`, `/v1/health` matched literally, so `--api-prefix` moves the health routes behind the key. The source comment and the warning text supply the wording.

## Implementation Notes

- `src/server/app.rs:75-77` defines `is_public_endpoint` as `matches!(path, "/" | "/health" | "/v1/health")`, with the comment at `:70-74` noting that `/health` is NOT public under `--api-prefix` (#1432).
- `src/server/cli_input.rs:972-978` emits the runtime warning about this interaction.
- `docs/server-features.md:270-272` states the public set; `--api-prefix` is introduced a few lines later (around `:278`) with no cross-reference.

## Acceptance Criteria

- [ ] `docs/server-features.md` states the `--api-prefix` and public-endpoint interaction where both features are described

---

## Original Suggestion

### Title: docs(server): document that --api-prefix removes the health endpoints from the public set

Setting `--api-prefix` silently makes the health endpoints require an API key, and the docs never mention it: the public-endpoint set is matched literally, so `/health` is not public. The server even warns about this at runtime — but a reader of `docs/server-features.md` cannot learn it.

## Evidence

- `src/server/app.rs:75-77` — `is_public_endpoint` matches only the literal `"/" | "/health" | "/v1/health"`; the comment at `:70-74` states that with `--api-prefix` set, `/health` is NOT public
- `src/server/cli_input.rs:972-978` — runtime `tracing::warn!` about exactly this interaction
- `docs/server-features.md:270-272` — "only `/`, `/health`, and `/v1/health` are public"; `:277-278` introduces `--api-prefix` six lines later with no cross-reference between the two passages

## Suggested fix

Add 2-3 sentences to the "Transport and access control" section connecting the two facts; the source comment and the warning text supply the wording.

## Acceptance criteria

- [ ] `docs/server-features.md` states the `--api-prefix` × public-endpoint interaction where both features are described

Contributor guide

Open the contributing guide

Research direction

Start in the "Transport and access control" section of docs/server-features.md around lines 270-278. Read the related comment in src/server/app.rs:70-77 and the warning in src/server/cli_input.rs:972-978 for the documented behavior. Add the requested 2-3 sentences, and consider the work done when the interaction between --api-prefix and the public endpoints is explicit there.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.