How manojuio/grpc-edge-proxy works
1. What this repo is
• grpc-edge-proxy is a Node.js edge gateway that translates incoming HTTP/JSON requests into outbound gRPC calls, then translates gRPC responses back to HTTP/JSON.
• The architecture is centered on protocol translation and backend request routing, not on business logic or storage.
2. Main runtime boundary
• The public entry point is the HTTP ingress layer in src/ingress-http/server.js.
• That layer is the only client-facing boundary; everything after it is internal translation and gRPC egress.
3. Application composition
• src/app.js is the bootstrap/wiring point.
• It initializes schema loading, request dispatching, and the HTTP server, so the app is assembled from three internal subsystems: ingress, translation core, and gRPC egress.
4. Ingress subsystem: HTTP to internal request handling
• src/ingress-http/server.js is the HTTP server.
• Its role is to accept requests, parse JSON bodies and request metadata, and hand the request off to the translation layer.
• Based on the README, this layer is implemented with Express and listens on port 8000.
5. Translation core: schema awareness and serialization
• src/translation-core/schema-loader.js loads .proto files from protos/ and builds the service/method schema registry.
• src/translation-core/serializer.js performs the format conversion between HTTP-friendly JSON and protobuf binary data.
• This is the main protocol boundary in the system: the proxy depends on schema metadata to know which gRPC service, method, and message types to use.
6. Egress subsystem: routing to gRPC backends
• src/egress-grpc/dispatcher.js chooses the target gRPC method and performs the invocation logic.
• src/egress-grpc/client-pool.js manages reusable gRPC client connections so the proxy avoids creating a new backend connection per request.
• Together these form the outbound call path from translated request to backend gRPC service.
7. Protocol definitions
• protos/user.proto is the canonical example schema in the repo.
• The proxy is schema-driven: service and message definitions in .proto files determine how HTTP requests map to gRPC RPCs and payload shapes.
8. End-to-end data flow
• Request enters via HTTP.
• The ingress layer passes request details into schema lookup and serialization.
• The dispatcher uses the schema and pooled client to call the matching gRPC method.
• The backend returns protobuf data, which is decoded back to JSON.
• The HTTP server returns the translated response to the client.
9. Testing and local backend simulation
• mock-server.js is a separate mock gRPC backend used for development and testing.
• It sits on the other side of the egress boundary and lets you validate routing, serialization, and client pooling without a real production backend.
10. Infrastructure and dependency choices that shape the architecture
• The implementation is Node.js/CommonJS.
• Express handles ingress HTTP traffic.
• @grpc/grpc-js, @grpc/proto-loader, and protobufjs support dynamic proto loading and gRPC/protobuf interoperability.
• There is no database, message queue, or persistent state layer in the repo; the proxy is stateless aside from in-memory client pooling and loaded schema metadata.
Main entry points: dispatcher.js Dispatcher · server.js HTTP server · schema-loader.js Schema loader · app.js App bootstrap
Components 8
Ingress
HTTP boundary that accepts client requests and hands them to the proxy pipeline
- HTTP server · Accepts JSON HTTP requests and forwards them into the proxy flow
src/ingress-http/server.js
Translation Core
Schema loading and payload conversion for HTTP-to-gRPC translation
- App bootstrap · Wires ingress, schema loading, and dispatch into one runtime
src/app.js - Schema loader · Loads .proto files and builds service/method metadata
src/translation-core/schema-loader.js - Serializer · Converts between JSON payloads and protobuf messages
src/translation-core/serializer.js
gRPC Egress
Backend routing and reusable client management for outbound RPCs
- Dispatcher · Selects the target gRPC method and drives invocation
src/egress-grpc/dispatcher.js - Client pool · Reuses backend gRPC connections across requests
src/egress-grpc/client-pool.js
Protocols
Proto definitions that drive schema-aware request mapping
- user proto · Example protocol definition that drives request-to-RPC mapping
protos/user.proto
Dev Backend
Mock gRPC server for local validation
- Mock server · Local gRPC backend used to exercise translation and routing
mock-server.js
Connections 13
- App bootstrap → HTTP server: starts · Bootstraps the client-facing HTTP boundary
- App bootstrap → Schema loader: loads · Initializes schema metadata at startup
- App bootstrap → Dispatcher: wires · Connects request translation to outbound routing
- HTTP server → Schema loader: uses · Looks up schema details for inbound requests
- HTTP server → Serializer: parses · Turns HTTP JSON bodies into internal message payloads
- HTTP server → Dispatcher: hands off · Forwards request context into the translation pipeline
- Schema loader → user proto: reads · Builds registry data from proto definitions
- Dispatcher → Schema loader: resolves · Finds the target service, method, and message types
- Dispatcher → Serializer: encodes/decodes · Converts request and response payloads across the protocol boundary
- Dispatcher → Client pool: borrows · Acquires reusable backend clients for invocation
- Dispatcher → Mock server: invokes · Routes calls to a gRPC backend during local development
- Client pool → Mock server: connects to · Maintains backend connections for outbound RPCs
- Serializer → HTTP server: returns · Feeds translated response data back to the HTTP layer