MILAB-XXXX: admin panel SDK — regen pl-client gRPC bindings (PF-0) [partial] by vgpopov · Pull Request #1698 · milaboratory/platforma

vgpopov · 2026-06-15T10:22:35Z

MILAB-XXXX: admin panel SDK — regen pl-client gRPC bindings (PF-0) [partial]

Bird's-eye

SDK side of the admin panel. The backend exposes a command bus (two frozen RPCs Query/Mutation on service Platform carrying a named command + JSON payload — see the pl PR). The SDK's job is to surface that to blocks through one generic adminDriver, wired once, so that every future admin feature is backend + block only.

block UI ─ getRawPlatformaInstance().adminDriver.query/mutation(name, payload)
   │  (desktop preload bridge — wired once)
   ▼  PlClient.query/mutation  →  standalone Query/Mutation RPC  (NOT PlTransaction)

API design ideas (SDK)

No transaction crosses the block boundary. The driver calls the standalone Query/Mutation RPCs via PlClient/LLPlClient (the ping/getUserRoot pattern), never PlTransaction.
One generic driver, frozen surface: adminDriver.query<T>(name, payload?) / mutation<T>(name, payload?). New admin commands need no new SDK methods.
Wired once through PlClient → pl-drivers AdminDriver → DriverKit → pl-middle-layer → sdk model. After that, extension is backend + block only.

What's in this PR (PF-0 only)

Regenerated TS gRPC bindings for service Platform from the admin-panel proto: PlatformClient now carries the Query/Mutation RPCs and CommandAPI types (lib/node/pl-client/src/proto-grpc/..., proto-rest/plapi.ts).

This is the foundation the rest of the SDK chain builds on.

Pending (separate commits/PR updates)

PF-1 — query/mutation passthrough on LLPlClient + PlClient.
PF-2 — AdminDriver (wraps PlClient) + public DriverKit interface.
PF-3 — register adminDriver in pl-middle-layer initDriverKit; SDK re-exports.
Desktop preload bridge (platforma-desktop-v2) + the admin-panel block UI are tracked separately.

Test plan

pnpm -C lib/node/pl-client build — generated stub compiles; query/mutation present on PlatformClient.
Full driver-chain build/lint lands with PF-1..PF-3.

Dependency

Consumes the proto from the pl admin-panel PR (PL-0). The bindings here were regenerated against that proto.

Draft — partial SDK slice (proto regen). Remaining PF tasks to follow.

…and CommandAPI types Add Command/CmdError/CommandResult messages plus Query and Mutation RPCs to service Platform in api.proto. Regenerate proto-grpc/* via generate-grpc.sh. PlatformClient and IPlatformClient now expose query()/mutation() methods.

…anonical state Revert google/rpc/error_details.ts, google/api/http.ts, google/rpc/code.ts, google/rpc/status.ts to their pre-PF-0 (HEAD~1) content. The previous commit accidentally regenerated them from a different cached googleapis .proto vintage (Copyright 2025 vs 2020), violating PF-0's "pure codegen / clean base" requirement. Also add a TRACKING comment to api.proto's Command bus RPCs noting that once PL-0 lands on pl/main, pnpm update-proto should be re-run to confirm the hand-written proto matches the canonical upstream version.

…age pollution

…ation RPCs

Regenerates the TS gRPC bindings for service Platform from the pl admin-panel proto, adding the Query/Mutation command-bus RPCs and CommandAPI types to PlatformClient. Partial: PF-1 (pl-client query/mutation passthrough), PF-2 (AdminDriver), PF-3 (middle-layer registration) still pending.

changeset-bot · 2026-06-15T10:22:42Z

⚠️ No Changeset found

Latest commit: 6fe8719

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

gemini-code-assist

Code Review

This pull request introduces new administrative and command-bus capabilities to the Platform service, including the ListUsers RPC, transactional ListGrants support, and generic Query and Mutation endpoints. Key feedback on these changes includes adding REST gateway support (google.api.http option) and pagination to the ListUsers endpoint. Additionally, it is recommended to replace the bytes fields in the command bus payloads (Command.payload and CommandResult.data) with google.protobuf.Value or Struct to prevent REST transcoding from forcing base64 encoding instead of raw JSON.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-15T10:23:51Z

  }
  rpc ListUserResources(AuthAPI.ListUserResources.Request) returns (stream AuthAPI.ListUserResources.Response) {}

+  rpc ListUsers(AuthAPI.ListUsers.Request) returns (AuthAPI.ListUsers.Response) {}


Unlike other unary RPCs in the Platform service, ListUsers is missing the google.api.http option. If this RPC needs to be accessible via the REST gateway (e.g., for the admin panel or external REST clients), please add the appropriate HTTP option.

Example:

rpc ListUsers(AuthAPI.ListUsers.Request) returns (AuthAPI.ListUsers.Response) { option (google.api.http) = { get: "/v1/users" }; }

Suggested change

rpc ListUsers(AuthAPI.ListUsers.Request) returns (AuthAPI.ListUsers.Response) {}

rpc ListUsers(AuthAPI.ListUsers.Request) returns (AuthAPI.ListUsers.Response) {

option (google.api.http) = {

get: "/v1/users"

};

}

gemini-code-assist · 2026-06-15T10:23:52Z

+  message ListUsers {
+    message Request {}
+
+    // Lists users known to the server. A user becomes known on first login;
+    // provisioned users who have never logged in do not appear.
+    message Response {
+      repeated User users = 1;
+    }
+  }


The ListUsers RPC currently returns all users in a single unpaginated list. If the number of users grows large, this can lead to performance bottlenecks, high memory usage, or exceeding gRPC message size limits.

Consider adding pagination fields (such as limit and offset/after or page tokens) to ListUsers.Request and ListUsers.Response to ensure the API scales efficiently.

gemini-code-assist · 2026-06-15T10:23:52Z

+    // payload is an opaque JSON object passed verbatim to the handler.
+    // May be empty when a command takes no arguments.
+    bytes payload = 2;


Since Query and Mutation are exposed via REST transcoding (google.api.http), using bytes for payload will cause the JSON transcoder to expect a base64-encoded string instead of a raw JSON object. This makes the REST API less intuitive to consume.

To allow clients to pass raw JSON objects directly, consider importing google/protobuf/struct.proto and using google.protobuf.Value or google.protobuf.Struct instead of bytes.

gemini-code-assist · 2026-06-15T10:23:52Z

+    // data is the JSON-encoded result. Empty when errors is non-empty.
+    bytes data = 1;


Since Query and Mutation are exposed via REST transcoding (google.api.http), using bytes for data in CommandResult will cause the JSON transcoder to return a base64-encoded string instead of a raw JSON object.

To allow clients to receive raw JSON objects directly, consider importing google/protobuf/struct.proto and using google.protobuf.Value or google.protobuf.Struct instead of bytes.

popoffvg added 5 commits June 13, 2026 22:29

[MILAB-XXXX]: PF-0: revert hand-authored proto/TS; fix status.ts vint…

5a6c4af

…age pollution

[MILAB-XXXX]: PF-0: regen TS gRPC bindings from pl-int with Query/Mut…

489db76

…ation RPCs

gemini-code-assist Bot reviewed Jun 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MILAB-XXXX: admin panel SDK — regen pl-client gRPC bindings (PF-0) [partial]#1698

MILAB-XXXX: admin panel SDK — regen pl-client gRPC bindings (PF-0) [partial]#1698
vgpopov wants to merge 5 commits into
mainfrom
MILAB-XXXX/admin-panel

vgpopov commented Jun 15, 2026

Uh oh!

changeset-bot Bot commented Jun 15, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// data is the JSON-encoded result. Empty when errors is non-empty.
		bytes data = 1;

Conversation

vgpopov commented Jun 15, 2026

Bird's-eye

API design ideas (SDK)

What's in this PR (PF-0 only)

Pending (separate commits/PR updates)

Test plan

Dependency

Uh oh!

changeset-bot Bot commented Jun 15, 2026

⚠️ No Changeset found

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants