fix: place gRPC proto at core-standard path and make grpc boot import-safe (#14)

Addresses review findings on the optional gRPC server.

#1 (main.py): the grpc server was imported at module top level, so importing
src.main required the generated stubs. Runtime.Init runs GenerateOpenAPI, which
imports src.main *before* Sync generates those stubs (and they are git-ignored,
so a fresh clone has none) — Init failed with ModuleNotFoundError. The import
now lives inside the startup handler; OpenAPI generation never fires startup, so
the module imports cleanly without stubs.

#2 (proto location): the proto was scaffolded at code/proto/api.proto, but
core's LoadEndpoints re-derives the gRPC contract from standards.ProtoPath
(proto/api.proto at the service root) and the manifest stores no proto bytes.
The endpoint therefore reloaded with zero RPCs and dependent services could not
generate clients. The proto now lives at the service-root standard path (Buf and
grpcEndpoint read it there), and defaultProtoPath is bound to standards.ProtoPath
so it can never drift again.

#3 (server.py): add_insecure_port returns 0 instead of raising when a port can't
be bound, so the server would "start" listening on nothing while FastAPI stayed
healthy. It now raises, which also fails the pod's HTTP readiness probe via the
shared lifespan (covers the gRPC-readiness gap).

Tests: added a reload regression test asserting the gRPC endpoint keeps its RPCs
after LoadEndpoints (would have caught #2), and a check that src.rpc is never
imported at module top level (would have caught #1).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: antoinetoussaint-byte

builder.go

@@ -140,10 +140,12 @@ func (s *Builder) Sync(ctx context.Context, _ *builderv0.SyncRequest) (*builderv
 }
 
 // syncGRPCServer regenerates the Python protobuf + grpc.aio server stubs from
-// the service-owned proto contract via Buf. Generation is cached on the proto
-// tree, so it re-runs deterministically only when the contract changes.
+// the service-owned proto contract via Buf. Buf reads proto/ under the service
+// root (matching the endpoint contract location) and writes the stubs into the
+// Python source tree. Generation is cached on the proto tree, so it re-runs
+// deterministically only when the contract changes.
 func (s *Builder) syncGRPCServer(ctx context.Context) error {
-	buf, err := proto.NewBuf(ctx, s.Local("code"))
+	buf, err := proto.NewBuf(ctx, s.Location)
 	if err != nil {
 		return s.Wool.Wrapf(err, "cannot create proto generator")
 	}
@@ -406,11 +408,12 @@ func (s *Builder) CreateEndpoints(ctx context.Context) error {
 }
 
 // grpcEndpoint builds the service-owned gRPC endpoint from the proto contract.
-// The proto path is resolved relative to the Python source dir (code/), where
-// the scaffolded proto/ tree and the generated stubs both live. It inherits the
-// same public/private visibility as the REST endpoint.
+// The proto path is resolved relative to the service root — the same location
+// core's LoadEndpoints re-reads it from — so the endpoint keeps its RPCs across
+// reloads and stays consumable by dependent services. It inherits the same
+// public/private visibility as the REST endpoint.
 func (s *Builder) grpcEndpoint(ctx context.Context) (*basev0.Endpoint, error) {
-	protoPath := s.Local("code/%s", s.FastAPI.Settings.GRPCServer.Proto)
+	protoPath := s.Local("%s", s.FastAPI.Settings.GRPCServer.Proto)
 	grpc, err := resources.LoadGrpcAPI(ctx, shared.Pointer(protoPath))
 	if err != nil {
 		return nil, s.Wool.Wrapf(err, "cannot load grpc proto %q", protoPath)

grpc_test.go

@@ -6,6 +6,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -91,7 +92,7 @@ func TestCreateRESTOnlyByDefault(t *testing.T) {
 	require.Equal(t, 1, len(builder.Endpoints))
 	require.Nil(t, builder.FastAPI.GRPCEndpoint)
 
-	_, err := os.Stat(filepath.Join(root, "code/proto/api.proto"))
+	_, err := os.Stat(filepath.Join(root, "proto/api.proto"))
 	require.True(t, os.IsNotExist(err))
 	_, err = os.Stat(filepath.Join(root, "code/src/rpc/server.py"))
 	require.True(t, os.IsNotExist(err))
@@ -123,8 +124,8 @@ func TestCreateWithGRPCServer(t *testing.T) {
 	require.Equal(t, standards.GRPC, builder.FastAPI.GRPCEndpoint.Api)
 
 	for _, rel := range []string{
-		"code/proto/api.proto",
-		"code/proto/buf.gen.yaml",
+		"proto/api.proto",
+		"proto/buf.gen.yaml",
 		"code/src/rpc/server.py",
 		"code/src/rpc/servicer.py",
 		"code/tests/rpc/test_grpc.py",
@@ -139,10 +140,54 @@ func TestCreateWithGRPCServer(t *testing.T) {
 	require.Contains(t, string(pyproject), "grpcio")
 	require.Contains(t, string(pyproject), "grpcio-tools")
 
-	main, err := os.ReadFile(filepath.Join(root, "code/src/main.py"))
+	assertMainImportsGRPCLazily(t, filepath.Join(root, "code/src/main.py"))
+}
+
+// assertMainImportsGRPCLazily guards the fix for the eager-import bug: importing
+// src.main (which openapi.py does at Init, before Sync generates the stubs) must
+// not require the generated gRPC package. The server import therefore lives
+// inside the startup handler (indented), never at module top level.
+func assertMainImportsGRPCLazily(t *testing.T, mainPath string) {
+	t.Helper()
+	content, err := os.ReadFile(mainPath)
+	require.NoError(t, err)
+	main := string(content)
+	require.Contains(t, main, "CODEFLY_GRPC_PORT")
+	require.Contains(t, main, "from src.rpc.server import serve")
+	for _, line := range strings.Split(main, "\n") {
+		if strings.HasPrefix(line, "from src.rpc.server import") || strings.HasPrefix(line, "import src.rpc") {
+			t.Fatalf("src.rpc must not be imported at module top level (breaks openapi generation before sync): %q", line)
+		}
+	}
+}
+
+// TestGRPCEndpointReloadsContract is the regression guard for the proto
+// location: core's LoadEndpoints re-derives the gRPC contract from disk at
+// standards.ProtoPath (service root). If the scaffolded proto lived anywhere
+// else, the reloaded endpoint would silently carry zero RPCs and dependent
+// services could not generate clients.
+func TestGRPCEndpointReloadsContract(t *testing.T) {
+	builder, _ := createServiceForTest(t, map[string]*agentv0.Answer{
+		HotReload:      confirmAnswer(false),
+		PublicEndpoint: confirmAnswer(false),
+		GRPCServer:     confirmAnswer(true),
+	})
+	ctx := context.Background()
+
+	endpoints, err := builder.Base.Service.LoadEndpoints(ctx)
 	require.NoError(t, err)
-	require.Contains(t, string(main), "CODEFLY_GRPC_PORT")
-	require.Contains(t, string(main), "from src.rpc.server import serve")
+
+	grpcEndpoint, err := resources.FindGRPCEndpoint(ctx, endpoints)
+	require.NoError(t, err)
+	grpc := resources.IsGRPC(ctx, grpcEndpoint)
+	require.NotNil(t, grpc)
+	require.NotEmpty(t, grpc.Rpcs, "reloaded gRPC endpoint lost its RPCs — proto not at core-standard path")
+
+	var names []string
+	for _, rpc := range grpc.Rpcs {
+		names = append(names, rpc.Name)
+	}
+	require.Contains(t, names, "Echo")
 }
 
 // TestDeploymentRendersGRPCPort proves the gRPC container/service ports appear

main.go

@@ -18,6 +18,7 @@ import (
 	runnersbase "github.com/codefly-dev/core/runners/base"
 	pythonrunner "github.com/codefly-dev/core/runners/python"
 	"github.com/codefly-dev/core/shared"
+	"github.com/codefly-dev/core/standards"
 	"github.com/codefly-dev/core/templates"
 	"github.com/codefly-dev/core/toolbox/lang"
 
@@ -43,9 +44,11 @@ const (
 )
 
 // defaultProtoPath is where the service-owned proto contract lives, relative
-// to the Python source dir (code/). Mirrors how openapi/api.swagger.json sits
-// beside the source. Buf generation and the gRPC endpoint both resolve it.
-const defaultProtoPath = "proto/api.proto"
+// to the service root. It is core's standards.ProtoPath: LoadEndpoints
+// (Builder + Runtime) and any dependent service re-derive the gRPC contract
+// from that exact location, so the proto has to sit there — the same way the
+// REST contract lives at openapi/api.swagger.json.
+const defaultProtoPath = standards.ProtoPath
 
 // GRPCServerSettings configures the optional service-owned grpc.aio listener.
 // Disabled by default: an unset grpc-server block leaves the service REST-only

templates/factory/code/src/main.py.tmpl

@@ -56,14 +56,17 @@ for plugin in plugins:
 # gRPC server — runs a grpc.aio listener in this process alongside FastAPI.
 # The port is provided by codefly at runtime; it falls back to the standard
 # gRPC port in container/Kubernetes where the mapping is fixed.
-from src.rpc.server import serve as _grpc_serve
-
 _grpc_server = None
 
 
 @app.on_event("startup")
 async def _start_grpc():
     global _grpc_server
+    # Imported inside the handler, not at module load: the generated stubs
+    # are produced by `codefly sync` and importing this module must not depend
+    # on them (openapi.py imports src.main to emit the schema before sync).
+    from src.rpc.server import serve as _grpc_serve
+
     port = int(os.environ.get("CODEFLY_GRPC_PORT", "9090"))
     _grpc_server = await _grpc_serve(port)
 

templates/grpc/code/src/rpc/server.py.tmpl

@@ -34,6 +34,10 @@ async def serve(port: int) -> grpc.aio.Server:
     """Start a grpc.aio server on ``port`` and return it (already started)."""
     server = grpc.aio.server()
     register(server)
-    server.add_insecure_port(f"[::]:{port}")
+    # add_insecure_port returns 0 (it does not raise) when the port can't be
+    # bound; without this check the server would "start" listening on nothing
+    # while FastAPI stays healthy, masking the failure.
+    if server.add_insecure_port(f"[::]:{port}") == 0:
+        raise RuntimeError(f"gRPC server could not bind port {port}")
     await server.start()
     return server

templates/grpc/code/tests/rpc/conftest.py.tmpl

@@ -5,7 +5,7 @@ import sys
 # The gRPC stubs are produced by `codefly sync` (Buf) before a normal test run.
 # Generate them here too so the suite is self-contained when run directly.
 _CODE = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
-_PROTO = os.path.join(_CODE, "proto")
+_PROTO = os.path.abspath(os.path.join(_CODE, "..", "proto"))
 _GENERATED = os.path.join(_CODE, "src", "rpc", "_generated")
 
 

templates/grpc/code/proto/api.proto.tmpl templates/grpc/proto/api.proto.tmpltemplates/grpc/code/proto/api.proto.tmpl renamed to templates/grpc/proto/api.proto.tmpl

@@ -1,6 +1,6 @@
 version: v1
 plugins:
   - plugin: buf.build/protocolbuffers/python
-    out: ../src/rpc/_generated
+    out: ../code/src/rpc/_generated
   - plugin: buf.build/grpc/python
-    out: ../src/rpc/_generated
+    out: ../code/src/rpc/_generated