fix(httpapi): make beads_dir and repo_root optional in ContextResponse (#5757)
GET /v0/beads/context required both. They are the only two members of the identity handshake that describe the SERVER's filesystem rather than the workspace's logical identity, and an absolute host path is not something a remote client can act on: it cannot open it, and project_id, database and backend are what tell two servers apart. The schema already called publishing them a cost "an operator accepts when binding beyond loopback". While they were required, accepting it was the only conforming option -- a deployment that did not want to disclose its filesystem layout had no way to withhold them and still serve a body matching this document. Making them optional restores that choice, in the only direction that cannot break a client that was already reading the document. No body changes. bd serve publishes both, always, exactly as before; the optionality is a promise to clients that absence is legal and must be tolerated, not a switch on the server. In Go the two generated members become *string, and the handler takes the addresses of the same published values. TestContextResponseRequiredSet pins the split from both sides -- the document's required list and the generated struct's pointer-ness -- so re-requiring a member re-imposes the disclosure only with a test edit, and dropping one that belongs there fails the same way. Co-authored-by: CI Bot <ci@beads.test>
This commit is contained in:
parent
997fac3b78
commit
d38ac728b5
5 changed files with 125 additions and 14 deletions
17
CHANGELOG.md
17
CHANGELOG.md
|
|
@ -9,6 +9,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
|
||||
### Changed
|
||||
|
||||
- **`beads_dir` and `repo_root` are now OPTIONAL members of `ContextResponse`
|
||||
on `GET /v0/beads/context`.** They are the only two members of the identity
|
||||
handshake that describe the SERVER's filesystem rather than the workspace's
|
||||
logical identity, and an absolute host path is not something a remote client
|
||||
can act on — it cannot open it. The document already called publishing them
|
||||
a cost "an operator accepts when binding beyond loopback"; while they were
|
||||
required, accepting it was the only conforming option. A deployment that
|
||||
does not want to disclose its filesystem layout can now withhold them and
|
||||
still serve a conforming body.
|
||||
|
||||
**No body changes.** `bd serve` publishes both, always, exactly as before —
|
||||
the relaxation is a promise to clients, not a switch on the server. What
|
||||
changes is what a client may assume: it MUST tolerate their absence, and
|
||||
MUST identify a workspace by `project_id`, `database` and `backend`, which
|
||||
stay required. In Go, `apigen.ContextResponse.BeadsDir` and `.RepoRoot`
|
||||
become `*string`.
|
||||
|
||||
- **`bd reclaim` summarizes the leases its replica guard declined instead of
|
||||
naming every one, every run** (wy-sp2l4). A lease granted by another replica
|
||||
is by construction never reclaimed here, so the audit was not a one-off: it
|
||||
|
|
|
|||
|
|
@ -957,6 +957,8 @@ type CompareAndSetMetadataResponse struct {
|
|||
}
|
||||
|
||||
// ContextResponse The server's identity handshake. Every member is a deliberate, permanent choice; the field set is an allowlist frozen by a test that checks it against BOTH this document and the generated Go struct, so a field cannot arrive here as a side effect of the server's configuration growing one. In particular the workspace's sync remote is EXCLUDED, in this and every future version, because remote URLs routinely embed credentials — as are the database bind host/port (advertising them invites clients to bypass this API and dial the database directly) and the loopback/non-loopback bind mode.
|
||||
//
|
||||
// TWO MEMBERS ARE OPTIONAL, and they are the only two that describe the SERVER's filesystem rather than the workspace's logical identity: `beads_dir` and `repo_root`. A client must be able to read them as absent. Everything a remote caller identifies a workspace by is elsewhere and stays required — `project_id`, `database`, `backend`, `dolt_mode` — and an absolute host path is not something a remote caller can act on in any case: it cannot open it. `bd serve` publishes both, so a client reading a `bd serve` today sees no change; what the relaxation buys is that a deployment which does not want to disclose its filesystem layout can withhold them and still serve a body that conforms to this document.
|
||||
type ContextResponse struct {
|
||||
// ApiVersion The path major this server serves. `v0` for this document.
|
||||
ApiVersion string `json:"api_version"`
|
||||
|
|
@ -967,8 +969,10 @@ type ContextResponse struct {
|
|||
// BdVersion The release version of the serving binary. The only field a client may compare as a version, and only for behavioral changes tied to a release.
|
||||
BdVersion string `json:"bd_version"`
|
||||
|
||||
// BeadsDir Absolute path of the served workspace's `.beads` directory. A host path, kept because it is the single-workspace server's only workspace-identity handshake; disclosing it to network peers is part of what an operator accepts when binding beyond loopback.
|
||||
BeadsDir string `json:"beads_dir"`
|
||||
// BeadsDir Absolute path of the served workspace's `.beads` directory, when the server discloses it. A host path: `bd serve` publishes it because it is a single-workspace server's most legible workspace-identity handshake for the operator reading it, and disclosing it to network peers is part of what that operator accepts when binding beyond loopback.
|
||||
//
|
||||
// OPTIONAL, and absent means only that this server does not disclose its filesystem layout — never that it has no workspace. A client MUST NOT require it, MUST NOT treat absence as an error, and has no use for the value beyond display: it is a path on the SERVER's filesystem, which the client cannot open. Identify the workspace by `project_id` and `database`, which are required.
|
||||
BeadsDir *string `json:"beads_dir,omitempty"`
|
||||
|
||||
// Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the one behavior token is `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string.
|
||||
//
|
||||
|
|
@ -984,8 +988,8 @@ type ContextResponse struct {
|
|||
// ProjectId Logical project identifier.
|
||||
ProjectId string `json:"project_id"`
|
||||
|
||||
// RepoRoot Absolute path of the served repository root. See `beads_dir`.
|
||||
RepoRoot string `json:"repo_root"`
|
||||
// RepoRoot Absolute path of the served repository root, when the server discloses it. OPTIONAL on the same terms as `beads_dir`; see it.
|
||||
RepoRoot *string `json:"repo_root,omitempty"`
|
||||
|
||||
// SchemaVersion The shared JSON schema version — the same constant the CLI's stdout JSON envelope reports. Diagnostic only: it can move for CLI-only reasons with no HTTP wire change, so clients MUST NOT branch on it.
|
||||
SchemaVersion int `json:"schema_version"`
|
||||
|
|
|
|||
|
|
@ -77,8 +77,12 @@ func (s *Server) requireNoQuery(w http.ResponseWriter, r *http.Request) bool {
|
|||
// it publish the database bind endpoint (advertising it invites clients to
|
||||
// bypass this API and dial a server whose trust model is "root with an empty
|
||||
// password on loopback") or the absolute host paths. BeadsDir and RepoRoot ARE
|
||||
// published, deliberately: they are the single-workspace server's only
|
||||
// workspace-identity handshake, and the document says so.
|
||||
// published, deliberately: they are the most legible workspace identity for
|
||||
// the operator reading a single-workspace server, and the document says so.
|
||||
//
|
||||
// Those two are also the response's only OPTIONAL members, and this server
|
||||
// always publishes them anyway. The optionality is the document's promise to
|
||||
// CLIENTS — that absence is legal and must be tolerated — not a switch here.
|
||||
//
|
||||
// The three members that are NOT the workspace's are named here, because they
|
||||
// are this surface's own: the API version, the schema version, and the
|
||||
|
|
@ -99,8 +103,8 @@ func contextResponse(info domain.ContextInfo, schemaVersion int, capabilities []
|
|||
Backend: published.Backend,
|
||||
DoltMode: published.DoltMode,
|
||||
Database: published.Database,
|
||||
BeadsDir: published.BeadsDir,
|
||||
RepoRoot: published.RepoRoot,
|
||||
BeadsDir: &published.BeadsDir,
|
||||
RepoRoot: &published.RepoRoot,
|
||||
ProjectId: published.ProjectID,
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -7092,9 +7092,22 @@ components:
|
|||
credentials — as are the database bind host/port (advertising them
|
||||
invites clients to bypass this API and dial the database directly) and
|
||||
the loopback/non-loopback bind mode.
|
||||
|
||||
|
||||
TWO MEMBERS ARE OPTIONAL, and they are the only two that describe the
|
||||
SERVER's filesystem rather than the workspace's logical identity:
|
||||
`beads_dir` and `repo_root`. A client must be able to read them as
|
||||
absent. Everything a remote caller identifies a workspace by is
|
||||
elsewhere and stays required — `project_id`, `database`, `backend`,
|
||||
`dolt_mode` — and an absolute host path is not something a remote
|
||||
caller can act on in any case: it cannot open it. `bd serve` publishes
|
||||
both, so a client reading a `bd serve` today sees no change; what the
|
||||
relaxation buys is that a deployment which does not want to disclose
|
||||
its filesystem layout can withhold them and still serve a body that
|
||||
conforms to this document.
|
||||
required:
|
||||
[api_version, bd_version, schema_version, backend, dolt_mode, database,
|
||||
beads_dir, repo_root, project_id, capabilities]
|
||||
project_id, capabilities]
|
||||
properties:
|
||||
api_version:
|
||||
type: string
|
||||
|
|
@ -7123,13 +7136,25 @@ components:
|
|||
beads_dir:
|
||||
type: string
|
||||
description: >-
|
||||
Absolute path of the served workspace's `.beads` directory. A host
|
||||
path, kept because it is the single-workspace server's only
|
||||
workspace-identity handshake; disclosing it to network peers is
|
||||
part of what an operator accepts when binding beyond loopback.
|
||||
Absolute path of the served workspace's `.beads` directory, when
|
||||
the server discloses it. A host path: `bd serve` publishes it
|
||||
because it is a single-workspace server's most legible
|
||||
workspace-identity handshake for the operator reading it, and
|
||||
disclosing it to network peers is part of what that operator
|
||||
accepts when binding beyond loopback.
|
||||
|
||||
|
||||
OPTIONAL, and absent means only that this server does not disclose
|
||||
its filesystem layout — never that it has no workspace. A client
|
||||
MUST NOT require it, MUST NOT treat absence as an error, and has no
|
||||
use for the value beyond display: it is a path on the SERVER's
|
||||
filesystem, which the client cannot open. Identify the workspace by
|
||||
`project_id` and `database`, which are required.
|
||||
repo_root:
|
||||
type: string
|
||||
description: Absolute path of the served repository root. See `beads_dir`.
|
||||
description: >-
|
||||
Absolute path of the served repository root, when the server
|
||||
discloses it. OPTIONAL on the same terms as `beads_dir`; see it.
|
||||
project_id:
|
||||
type: string
|
||||
description: Logical project identifier.
|
||||
|
|
|
|||
|
|
@ -717,6 +717,67 @@ func TestContextResponseAllowlist(t *testing.T) {
|
|||
}
|
||||
}
|
||||
|
||||
// contextResponseOptional is the set of ContextResponse members a client must
|
||||
// be able to read as ABSENT. Everything else on the allowlist is required.
|
||||
//
|
||||
// Both entries describe the SERVER's filesystem rather than the workspace's
|
||||
// logical identity, and a remote client cannot act on an absolute host path —
|
||||
// it cannot open it, and `project_id`, `database` and `backend` are what tell
|
||||
// two servers apart. The schema's own text calls publishing them a cost the
|
||||
// operator accepts; while they were required, accepting it was the only
|
||||
// conforming option.
|
||||
var contextResponseOptional = []string{"beads_dir", "repo_root"}
|
||||
|
||||
// TestContextResponseRequiredSet pins the split from both sides: the document's
|
||||
// `required` list and the generated struct's pointer-ness, which is what tells
|
||||
// a Go client that absence is representable.
|
||||
//
|
||||
// Without it the relaxation is one edit from being undone, in either direction:
|
||||
// re-listing a member under `required` re-imposes the disclosure on every
|
||||
// deployment, and dropping one that belongs there turns a guaranteed member
|
||||
// into an optional one for every client that had stopped checking.
|
||||
func TestContextResponseRequiredSet(t *testing.T) {
|
||||
optional := map[string]bool{}
|
||||
for _, name := range contextResponseOptional {
|
||||
optional[name] = true
|
||||
}
|
||||
wantRequired := map[string]bool{}
|
||||
for _, name := range contextResponseAllowlist {
|
||||
if !optional[name] {
|
||||
wantRequired[name] = true
|
||||
}
|
||||
}
|
||||
|
||||
doc := loadSpec(t)
|
||||
schema := mapAt(t, mapAt(t, mapAt(t, doc, "components"), "schemas"), "ContextResponse")
|
||||
gotRequired := map[string]bool{}
|
||||
for _, name := range toStrings(t, schema["required"]) {
|
||||
gotRequired[name] = true
|
||||
}
|
||||
if extra := diff(gotRequired, wantRequired); len(extra) > 0 {
|
||||
t.Errorf("ContextResponse requires members this test expects to be optional: %v\n"+
|
||||
"requiring one means no deployment may withhold it", extra)
|
||||
}
|
||||
if missing := diff(wantRequired, gotRequired); len(missing) > 0 {
|
||||
t.Errorf("ContextResponse no longer requires: %v\n"+
|
||||
"a client that had stopped checking for these now has to", missing)
|
||||
}
|
||||
|
||||
rt := reflect.TypeOf(apigen.ContextResponse{})
|
||||
for i := range rt.NumField() {
|
||||
f := rt.Field(i)
|
||||
name := strings.Split(f.Tag.Get("json"), ",")[0]
|
||||
isPointer := f.Type.Kind() == reflect.Pointer
|
||||
if optional[name] && !isPointer {
|
||||
t.Errorf("generated ContextResponse.%s is %s; an optional member must be a pointer or the server cannot omit it",
|
||||
f.Name, f.Type)
|
||||
}
|
||||
if !optional[name] && isPointer {
|
||||
t.Errorf("generated ContextResponse.%s is %s; a required member must not be nil-able", f.Name, f.Type)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestClaimRequestMembersMatchTheHandler is the same gate for the REQUEST side
|
||||
// of the claim, where the same unpinned-surface hazard runs the other way.
|
||||
//
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue