gRPC API

GrpcTransport is CodeGraph’s async Python client for a running GoCPG gRPC server. It returns the same Pydantic result models used by the subprocess transport. This page explains the client boundary and routes readers to the canonical protobuf files instead of copying every request field into a second, manually maintained schema.

Canonical services

The generated Python stubs live under src/services/gocpg/proto/gocpg/v1/. The maintained client implementation is split across src/services/gocpg/runtime/grpc_transport.py and the neighboring grpc_transport_*.py mixins.

Connection configuration

Send and receive messages are capped at 64 MiB. If grpc_tls_cert is absent, the client uses grpc.aio.insecure_channel; this is suitable only inside an already trusted boundary. Supplying a certificate creates a server-authenticated TLS channel. It does not configure client-certificate authentication.

Operation groups

• parse, update, ci_update, and create_indexes build or update a DuckDB CPG. Parse and update consume server streams and can report progress through the configured callback.
• query, stats, quality_stats, frontend, branch, and submodule methods use QueryService.
• search, scan, and validate_rule use PatternService; scan is streaming.
• nav_symbols, nav_callers, nav_callees, nav_hierarchy, nav_outline, nav_usages, nav_deps, and nav_resolve use NavigationService.
• lifecycle_status calls GetDatabaseStatus; watch_database_status calls WatchDatabaseStatus; freshness, maintenance, and plan_refresh use the corresponding lifecycle RPCs, including PlanRefresh.

Use the Python method signatures for typed client input and the protobuf files for the wire contract. Do not infer a request field from an older rendered copy of this page.

Paths and deadlines

Database-scoped operations require an explicit db_path or typed request field that resolves to one. Source, repository, output, and database paths are normalized to absolute paths before the RPC is sent. The GoCPG server must be able to interpret those paths in its own runtime context; a client-local path is not automatically mounted into a remote server.

The transport applies operation-specific deadlines: parse defaults to 3600 seconds; update and CI update to 600; index creation and maintenance to 300; query and pattern operations commonly use 60; navigation and unary status calls commonly use 30; status watching defaults to 60. Callers can provide the typed method’s timeout when a different bounded deadline is required.

Failure handling

DEADLINE_EXCEEDED is mapped to GoCPGTimeoutError. Other gRPC statuses are mapped to GoCPGProcessError with the status name and server details. A parse or update stream that ends without a final result returns the bounded result model assembled from the requested output path; verify expected graph content with a separate health or metadata operation.

For an unavailable server, first verify host, port, trust chain, and bearer metadata. Then run a lightweight health or metadata call before retrying a long parse. Do not disable TLS or remove the API key merely to turn an authorization or certificate failure into a connection.

Security boundary

The transport can carry an API key and validate a server certificate, but it does not decide tenant authorization or path ownership. Keep credentials out of source files, use a trusted secret provider, limit the server’s filesystem access, and expose plaintext insecure_channel only on a protected local network boundary.

Raw db_path belongs to the Python gRPC client. Agent-facing MCP calls resolve storage through project/runtime context.

Source of truth

• src/services/gocpg/runtime/grpc_transport.py — channel management and core CPG operations.
• src/services/gocpg/runtime/grpc_transport_query.py — query and metadata methods.
• src/services/gocpg/runtime/grpc_transport_pattern.py — pattern methods.
• src/services/gocpg/runtime/grpc_transport_navigation.py — navigation methods.
• src/services/gocpg/runtime/grpc_transport_lifecycle.py — lifecycle and refresh methods.
• src/services/gocpg/runtime/grpc_transport_errors.py — stable error mapping.
• gocpg/api/proto/gocpg/v1/ — authoritative protobuf service and message contracts.