gRPC API

NetClamp’s gRPC surface lives at 127.0.0.1:9846 and mirrors what the REST API does, with one bonus: low-latency streaming for live events. If your client is gRPC-native, use this; if you’re scripting with curl or PowerShell Invoke-RestMethod, REST is simpler.

Authentication

Same bearer token as REST (C:\ProgramData\NetClamp\auth.token). Pass it as gRPC metadata:

authorization: Bearer <token>

Service definition

The single service is netclamp.NetClampService. Highlights:

GetStatus

Service health snapshot (same fields as /api/v1/status).

ListApps / GetApp

Per-app traffic data.

ListConnections

Live socket table.

CreateRule / UpdateRule / DeleteRule / ListRules

Rule CRUD.

SetQuota / GetQuota / ListQuotas / DeleteQuota

Quota CRUD.

StreamEvents

Server-streaming RPC: quota busts, rule sync alerts, BFE recovery events. Connect once, leave open.

Getting the .proto

The schema is published with every release at:

C:\Program Files\NetClamp\proto\netclamp.proto

Or copy it out of the installer’s proto/ directory before installing.

Quick start — Python

pip install grpcio grpcio-tools
python -m grpc_tools.protoc -I"C:\Program Files\NetClamp\proto" `
    --python_out=. --grpc_python_out=. netclamp.proto

import grpc
import netclamp_pb2, netclamp_pb2_grpc

with open(r"C:\ProgramData\NetClamp\auth.token") as f:
    token = f.read().strip()

channel = grpc.insecure_channel("127.0.0.1:9846")
stub = netclamp_pb2_grpc.NetClampServiceStub(channel)
md = [("authorization", f"Bearer {token}")]

status = stub.GetStatus(netclamp_pb2.GetStatusRequest(), metadata=md)
print(f"WFP active: {status.wfp_active}, rules: {status.active_rules}")

for evt in stub.StreamEvents(netclamp_pb2.StreamEventsRequest(), metadata=md):
    print(evt.kind, evt.detail)

Quick start — Go

protoc --go_out=. --go-grpc_out=. -I"C:\Program Files\NetClamp\proto" netclamp.proto

conn, _ := grpc.Dial("127.0.0.1:9846", grpc.WithInsecure())
md := metadata.New(map[string]string{"authorization": "Bearer " + readToken()})
ctx := metadata.NewOutgoingContext(context.Background(), md)
client := pb.NewNetClampServiceClient(conn)
status, _ := client.GetStatus(ctx, &pb.GetStatusRequest{})

When to choose gRPC over REST

You need event streams (quota busts, rule sync state changes) and don’t want to manage Server-Sent Events reconnection logic.
You’re writing a daemon that talks to NetClamp continuously and care about per-RPC overhead.
Your language has good gRPC tooling already wired (Go, Rust, C#, Java).

For one-shot scripts, REST is usually less ceremony.

Status codes

Standard gRPC status codes apply:

OK

Success.

UNAUTHENTICATED

Missing or wrong bearer token.

INVALID_ARGUMENT

Request body failed validation.

NOT_FOUND

Resource doesn’t exist.

FAILED_PRECONDITION

E.g. RATE_LIMIT requested but the kernel driver isn’t loaded.

INTERNAL

Unexpected. The server log has the detail.

UNAVAILABLE

Transient — retry with backoff.