oceanbase / oceanbase/powercontext

feat(api): add Server protocol discovery and persistent deployment identity

Open
#1,655 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.