oceanbase / oceanbase/powercontext
feat(api): add Server protocol discovery and persistent deployment identity
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 212
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 199
Description
Feature description
Implement the Server-owned compatibility and deployment identity contract requested by D1 in RFC #1455. Desktop and other clients need to distinguish a supported API contract from a healthy endpoint and recognize when a connection now points to a different logical deployment.
Problem and proposed solution
At aa697c5315204249e090acdf1a00d0582e851c5f, liveness/readiness, /v1/capabilities, and /v1/access/me exist, but the proposed server-info endpoint does not. These existing interfaces describe runtime availability and authorization; they do not establish the RFC's protocol compatibility or persistent deployment identity.
Define and implement the proposed GET /v1/server-info contract, including product/schema identification, package version, API contract version, feature contracts, and an opaque persistent server_id. Final schema, feature names, version rules, and persistence/restore semantics should be agreed with Server maintainers before implementation.
Acceptance criteria
- Publish the schema and operation in OpenAPI and document major/minor compatibility, unknown optional fields, and feature-contract interpretation.
- Apply the configured Server authentication/authorization policy, including authenticated deployments; preserve existing unauthorized, forbidden, and authentication-unavailable semantics. Discovery does not grant permission to other operations.
- Return no credentials, local paths, or unauthorized resource inventory.
- Preserve the logical deployment ID across restart, supported upgrade, and supported restore of the same deployment.
- Define and test initialization for a clone that becomes a different deployment; cooperating replicas of one logical deployment share its identity.
- Keep this identity distinct from Access's configurable
deployment_id. It is not a substitute for TLS, credentials, or verified local service ownership. - Document how compatibility, runtime capabilities, and Principal/family permissions combine without treating any one as sufficient authorization.
- Test persistence and supported identity lifecycle behavior, configured authentication modes, and version/feature responses through public interfaces. Define restore/clone integration explicitly without requiring a new general-purpose backup system in this issue.
- Run
make api-generate,make contract-test, relevant behavior tests, and required checks; do not hand-edit generated Python sources.
Alternatives considered
- Package version alone does not identify a logical deployment or specify per-feature contract compatibility.
- Health/capability probes cannot prove compatibility with untested mutations.
- Desktop-generated identity would disagree across clients and cannot define Server restore/clone behavior.
Additional context
- Refs #1455 (D1) and #1428; related deployment/restore work includes #1430 and #1421.
- Accepted handshake requirements.
- Current Server routes and OpenAPI.
- Open for community implementation in a focused PR targeting
master. Coordinate schema/lifecycle decisions before consumers depend on them. - Desktop scaffolding and the bounded connect-only workflow can proceed with explicitly qualified compatibility profiles while this contract is developed.
Desktop consumer: #1654.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read docs/en/rfcs/1455-desktop-control-center.md, src/powercontext/server/app.py, and openapi/powercontext.yaml first, then coordinate with Server maintainers on the schema, feature names, version rules, and identity lifecycle. Done means the public endpoint, OpenAPI documentation, authentication behavior, persistence/restore/clone semantics, and tests are implemented; run make api-generate, make contract-test, and the required checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, python
- Domain
- api, authentication, backend, documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100