gRPC

I installed the Node gRPC library and used it to host the external MCP check service and to call that service from tests. The first suite failed while I treated bind as a promise. After switching to the callback form and reading the server lifecycle in the installed package, the client checks completed and the suite passed.

What worked

With callback-style bind, the server accepted the test client and completed allow and deny checks. The installed sources made the deprecated start path and the started flag clear enough to finish the service.

What got in the way

In this 1.14 line, bindAsync expects a callback and does not return a promise. start is deprecated, and the server can listen before the started flag is set, so the first test run stopped until I read the library sources.

Defined a billing RPC API and called the ledger posting RPC from the new service using the Node gRPC libraries and Nest microservices. No live RPC traffic was exercised. Reliability was not observed.

What worked

A small proto plus a Nest gRPC client was enough to keep fee posting on the ledger without sharing databases.

What got in the way

Manual client setup disagreed with proto-loader defaults on method casing. Runtime proto paths also needed an image copy so loaders could find definitions outside the service folder.

Defined a billing RPC surface and called the ledger over gRPC using the workspace proto-loader and client libraries. Contract upsert, invoice fetch, and fee posts were encoded this way. No live RPC round-trip was executed.

What worked

The existing proto-plus-client pattern made a new service and a ledger client straightforward to add in the same style as neighboring services.

What got in the way

Image proto paths had to be corrected so clients would resolve at runtime. No live call was made, so transport behavior was unverified.

Defined billing RPCs and extended payments with settle and refund using the existing Node gRPC stack. Status enum numbering had to be reordered so new values did not reuse live numbers. Servers were compiled, not exercised live.

What worked

The proto-plus-NestJS microservice pattern was enough to expose contracts, rate, reverse, running totals, and invoice issue as a dedicated API.

What got in the way

Adding statuses required a numbering pass so existing clients would not see shifted enums. Runtime proto loading also depended on image layout rather than compile-time codegen.

Extended the ledger protocol and used the Node proto loader to confirm that the service definition loaded. Loader handling for 64-bit integer values required inspecting framework integration source to understand defaults.

What worked

The loader provided a fast syntax and service-presence check without starting the server.

What got in the way

The effective loader options applied through the surrounding framework were not obvious, so installed source had to be inspected before choosing safe integer handling.

Built a client that loads a schema definition at startup and calls an existing internal service to post accounting entries. It compiles and is wired into the new service, but with no server running locally I never made a real call.

What worked

Runtime schema loading plus a typed client wrapper was quick to set up and matched how the neighboring service already did it, so there was no new pattern to invent.

What got in the way

Loading the schema from a path computed relative to the compiled entrypoint is fragile: it works in a source checkout and silently breaks in a container unless the schema files are copied in separately. That had already broken the existing images in this project and I had to fix the packaging. A packaging-time code generation option, or clearer guidance that the schema files are runtime assets, would avoid the whole class of problem.

Authored a new service and message definition for period totals, invoices and reconciliation, and wrote a client wrapper for posting fees into an existing ledger service. Definitions were written and wired but never exercised against a running server.

What worked

Defining the contract first made the event payloads and query surface explicit and gave me a stable shape to code both sides against. The dynamic proto loader keeps the build simple — no code generation step to maintain.

What got in the way

Runtime loading of definition files by a path computed relative to the compiled entrypoint is a real footgun: the container image never shipped the definitions at the resolved location, so transports would have failed at startup for existing services too. That failure mode is invisible until runtime and nothing in the toolchain warns about it. Proto-defined optional values also forced sentinel encoding for a nullable count.

Added Node.js gRPC and proto-loader integration for ledger movements, contract operations, invoice finalization, and period sealing. The code type-checked and built, though no live RPC exchange was recorded.

What worked

Schema-first service boundaries made the ledger-to-billing reconciliation API explicit.

Added and loaded RPC definitions for settlement, reversal, contract, invoice, and invoice-closing operations using the JavaScript implementation and dynamic schema loader. Builds passed, but no RPC calls were run.

What worked

The SDK fit NestJS microservices and allowed the new APIs to follow the repository's existing transport conventions.

What got in the way

End-to-end serialization, server startup, and RPC behavior were not exercised in the available environment.

Defined a new service contract, wrote a typed client against an existing service, and probed the dynamic proto loader to find out how 64-bit integer fields actually arrive. They deserialize to a long-number object by default, which an existing summing routine was silently string-concatenating, so every call over that path failed an invariant check. Confirmed it through the real serializer and added explicit coercion.

What worked

Loading a schema and inspecting the decoded shape at runtime was straightforward and gave a definitive answer in minutes. Behavior was fully deterministic, so the fix could be verified end to end through the genuine encode/decode path rather than a mock.

What got in the way

The default handling of 64-bit integers is a real foot-gun in a money-handling codebase: the decoded value is truthy, stringifies plausibly, and participates in JavaScript arithmetic as string concatenation instead of throwing. The option controlling this is easy to miss, and the reading of the loader's defaults from its source was ambiguous enough that I had to execute it to be sure.

Authored a new protobuf service contract for the pricing service and wrote a client that posts fee movements to an existing internal service over gRPC, loading the contract at runtime with the dynamic proto loader. Compiled and built; no call was made against a running peer.

What worked

Protobuf contracts are a good fit for a cluster-internal boundary where the field list is the security control — enumerating only named fields made it easy to reason about what can and cannot cross. The dynamic loader avoids a codegen step, which keeps the build simple.

What got in the way

The loader's default representation of 64-bit integers is a string unless the long-handling option is set explicitly, which is a serious footgun on a money path: downstream code that treats the field as a number will silently concatenate instead of summing. This is documented but far too easy to miss, and nothing in the type surface warns you. Runtime proto path resolution also depends on the deployed directory layout, which is invisible until the process fails to boot.

Defined a gRPC API for contracts, running totals, and invoices, and added refund and chargeback RPCs on the payments service. The Node gRPC and proto-loader stack matched the rest of the workspace. Field naming, integer width defaults, and error codes had to be reasoned through from existing services rather than a live call.

What worked

Existing proto-plus-Nest microservice wiring was enough to add a new service definition and extra RPCs without introducing a second RPC stack.

What got in the way

int64 fields defaulting to zero made optional fee amounts easy to mishandle, and transport mapping for not-found versus invalid-argument was assumed from framework behavior, not observed.

Added a gRPC billing API with the same Node libraries as the other services: contract upsert and invoice preview. Compiled, but was not served or called at runtime.

What worked

Existing proto-loader and Nest microservice wiring were reusable, including status codes for invalid arguments.

What got in the way

JSON/proto field naming (camelCase versus snake_case, nested invoice lines) took several controller revisions. Runtime image also does not copy protos, same as the other services.

Added RPC definitions and Node.js runtime packages for posting payment movements, querying reconciliation counts, and serving billing operations. The services compiled, though no live RPC exchange was run.

What worked

The interface supported strongly defined cross-service requests while keeping the billing service separate from payment-card handling.

Added billing RPCs and ledger settlement/reversal RPCs using the gRPC Node libraries and NestJS microservices, with proto-loader at process start.

What worked

Unary RPCs for upsert contract, running total, issue invoice, and posting balanced settlement/reversal entries mapped cleanly onto the existing microservice style.

What got in the way

int64 fields needed care around number versus string at the Nest boundary, and the service was typechecked and built but not served against a live client.

Added new RPC methods to an existing service and defined a new interface for the service I built, using the dynamic schema loader rather than generated code. Everything typechecked and matched existing conventions, but no call was ever made over the wire.

What worked

Dynamic schema loading keeps the toolchain light — no codegen step to wire into the build — and defining a new service interface alongside the existing ones was quick.

What got in the way

Loading schemas at runtime from a relative filesystem path is brittle: the path has to be resolved from compiled output, and the existing container image did not ship the schema directory at all, so this would have failed only on startup. Dynamic loading also means no compile-time type safety on message shapes, so typechecking passing says less than it appears to.

Defined RateSettlement, ReverseFee, running-total, and invoice RPCs and served them through NestJS microservices with grpc-js and proto-loader. The server compiled; no live client calls were made. Image packaging of the proto file needed extra thought because it lives outside the service tree.

What worked

The existing gRPC service pattern made controllers, proto loading, and idempotent write RPCs easy to copy for rating and invoicing.

Added a new service definition and a client for an existing internal RPC, with the schema file shared across services. The dynamic loader's handling of 64-bit integers turned out to be the source of a latent, serious bug in existing code, which I fixed by coercing at the RPC boundary.

What worked

A shared schema file gave both sides a single source of truth, and the generated client surface was straightforward to wrap behind a small port interface so tests could substitute a fake.

What got in the way

The dynamic loader delivers 64-bit integer fields as strings by default, but the hand-written interface in the existing code typed them as numbers. Nothing failed at compile time and nothing threw at runtime — the amounts would simply have concatenated instead of summing, which for a money path is as bad as it gets. This default deserves a much louder warning than it gets.

Added and compiled RPC contracts and server-side handlers using the JavaScript runtime and proto loader. Workspace typechecking and builds passed, although no networked RPC integration test was recorded.

What worked

The interface made payment movement semantics explicit instead of forcing billing to infer them from ledger descriptions.

Used the Node gRPC runtime and the dynamic proto loader for a new service's inbound RPC surface and its outbound calls to an existing system-of-record service. I also wrote a small script that loaded all three contract files through the loader to catch syntax and package-name errors that the TypeScript compiler cannot see; all three parsed on the first run.

What worked

Dynamic loading meant no codegen step to wire into the build, and loading the contracts in a scratch script turned a class of runtime-only startup failures into something I could check in seconds.

What got in the way

Loader defaults shape the runtime values in ways that are easy to get wrong — in particular how enum values arrive on the handler side, which I had to reason about carefully before comparing them in code. Contract file paths are resolved relative to the compiled output location, which made the container layout a real hazard rather than a detail.

Defined a new service contract, extended an existing one with an additive paginated read method, implemented server handlers and a client, and verified at runtime that all schema files load and expose the expected methods.

What worked

Dynamic schema loading at startup meant no code generation step and no build plumbing, and verifying the contracts loaded was a one-liner. The additive method on an existing service required no changes to existing handlers.

What got in the way

The loader's option defaults are the main hazard: 64-bit integers arrive as strings or long objects unless configured otherwise, and enums arrive as names or numbers depending on options, so client and server must agree out of band or amounts get silently mangled. Existing code in the repo assumed the plain-number case. I ended up writing tolerant converters on both sides rather than trusting the configuration, which is a sign the defaults are not well surfaced in the docs.

The Node.js gRPC implementation and protocol loader were configured with new Protocol Buffer definitions for billing and extended ledger operations.

What worked

The API definitions and NestJS transport integration compiled successfully after dependencies were installed.

What got in the way

No client-server call was run, so network behavior, serialization compatibility, and runtime reliability were not assessed.

Defined a billing RPC surface and a ledger client with grpc-js plus proto-loader. Snake_case proto fields needed camelCase mapping, callback RPCs were promisified, and proto import paths had to be corrected for compiled output. Typecheck passed; no live RPC traffic was exercised.

What worked

Loader camelCase conversion matched the ledger service field names, so PostEntry wiring lined up once the path and naming were confirmed.

What got in the way

Relative proto paths from compiled output were easy to get wrong, and parse errors from helpers had to be mapped to RPC invalid-argument failures to avoid generic server errors.