fauxrpc

package module
v0.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2026 License: MIT Imports: 22 Imported by: 2

README

FauxRPC

Go Go Report Card Go Reference

FauxRPC accelerates development and testing by generating fake implementations directly from Protobuf and OpenAPI schemas. A single server can expose gRPC, gRPC-Web, Connect, and HTTP/REST services without writing an implementation.

Why FauxRPC?

  • Faster Development & Testing: Work independently without relying on fully functional backend services.
  • Isolation & Control: Test frontend components in isolation with controlled fake data.
  • Multi-Protocol Support: Supports multiple protocols (gRPC, gRPC-Web, Connect, and REST).
  • OpenAPI Support: Serve OpenAPI operations, validate requests, generate schema-shaped bodies and headers, and browse interactive API documentation.
  • Prototyping & Demos: Create prototypes and demos quickly without building the full backend. Fake it till you make it.
  • API Stubs: Define static or dynamic API responses with powerful stubs featuring CEL expressions for precise behavior control. Stubs can be defined using config files or dynamically at runtime.
  • Improved Collaboration: Bridge the gap between frontend and backend teams.
  • Plays well with others: Generated data follows OpenAPI schema constraints and tries to follow any protovalidate constraints defined in Protobuf schemas.
  • Request Validation: Validate HTTP requests against OpenAPI operations and RPC messages with protovalidate.

See the documentation website for more!

Get Started

Install via source
go install github.com/sudorandom/fauxrpc/cmd/fauxrpc@v0.27.2
Pre-built binaries

Binaries are built for several platforms for each release. See the latest ones on the releases page.

Usage

Running the Server

The core command is fauxrpc run, which starts the server based on your Protobuf or OpenAPI schema. You can combine flags to configure the server on startup.

For example, this command starts the server with a specific schema, loads a stub for a method, and enables the dashboard:

fauxrpc run --schema=buf.build/connectrpc/eliza --stubs=example/stubs.eliza --dashboard
Loading Schemas

You must provide schemas so FauxRPC knows which services to fake. Protobuf descriptors and OpenAPI specifications use the same --schema option, and you can mix and match sources.

From a local file
fauxrpc run --schema=service.binpb
From the Buf Schema Registry (BSR)
fauxrpc run --schema=buf.build/bufbuild/eliza
From an OpenAPI specification
fauxrpc run --schema=openapi.yaml

OpenAPI specifications can be YAML or JSON files, URLs, or directories containing specifications. See OpenAPI Support for a complete example.

From multiple sources at once
fauxrpc run --schema=service.binpb --schema=openapi.yaml

OpenAPI Support

FauxRPC can serve OpenAPI operations alongside Protobuf services. It detects OpenAPI YAML and JSON documents passed through the same --schema option used for Protobuf descriptors.

For an operation without a matching stub, FauxRPC:

  • Matches the HTTP method, server base path, and templated path.
  • Validates path parameters, query parameters, headers, and request bodies against the operation.
  • Selects a successful response, preferring 200, then 201, then the default or first declared response.
  • Generates response bodies from schemas, including examples, defaults, enums, constraints, formats, arrays, objects, allOf, oneOf, anyOf, and recursive references.
  • Generates response headers declared by the selected OpenAPI response.

Explicit OpenAPI examples and defaults are preserved. Other generated values vary between requests by default. Use --static-seed to make unstubbed OpenAPI and Protobuf responses deterministic:

fauxrpc run --schema=openapi.yaml --static-seed
Swagger Petstore example

The repository includes a locally runnable adaptation of the canonical Swagger Petstore OpenAPI 3.0 specification, plus several conditional stubs:

fauxrpc run \
  --schema=example/swagger-petstore-openapi.yaml \
  --stubs=example/stubs.swagger-petstore.yaml

Try the path-parameter and query-parameter stubs:

curl http://127.0.0.1:6660/api/v3/pet/42
curl "http://127.0.0.1:6660/api/v3/pet/findByStatus?status=available"

The interactive OpenAPI documentation is available at http://127.0.0.1:6660/fauxrpc/openapi-docs/. The served document points its primary server URL at FauxRPC while preserving the schema's base path.

OpenAPI stubs

OpenAPI stubs can target an operationId or an HTTP path and method. Matches can be narrowed using path parameters, query parameters, headers, or a truthy GJSON path into the request body.

stubs:
  - name: The answer to pets, life, and everything
    target:
      operationId: getPetById
    match:
      pathParams:
        petId: "42"
    response:
      status: 200
      headers:
        X-Pet-Mood: existential
      body:
        id: 42
        name: Deep Thought
        photoUrls:
          - https://fauxrpc.local/pets/deep-thought.jpg
        status: available

Load the file with --stubs:

fauxrpc run --schema=openapi.yaml --stubs=openapi-stubs.yaml

Using Stubs

While FauxRPC generates fake data by default, stubs let you define specific, predictable responses for RPC and OpenAPI operations. This is useful for testing particular scenarios.

You can load a single stub file or an entire directory of them.

Add --only-stubs to disable generated fallback responses. An OpenAPI operation without a matching stub returns HTTP 501 Not Implemented; Protobuf RPCs return an empty response message.

Load a single stub file
fauxrpc run --schema=eliza.binpb --stubs=example/stubs.eliza/say.json
Load all stubs from a directory
fauxrpc run --schema=eliza.binpb --stubs=example/stubs.eliza/

Proxying and Ingesting Real Traffic

FauxRPC can act as an intercepting proxy to ingest real gRPC/Connect traffic and automatically generate stateful, predictable mock profiles (stubs) on disk.

When in proxy mode, FauxRPC forwards incoming requests to an upstream server, captures the request and response payloads, translates them into the stub format, and writes/appends them to files under a structured directory by service/method (e.g., <record-dir>/<service>/<method>.json).

To run FauxRPC in proxy mode:

fauxrpc run --proxy-to=127.0.0.1:8080 --record-dir=stubs/
  • --proxy-to: The address of the upstream gRPC or Connect server to forward requests to.
  • --record-dir: The directory path where the recorded stubs should be saved, structured by service and method.
Unimplemented Fallback

If the upstream server returns an UNIMPLEMENTED status code (indicating that the endpoint is not yet implemented), FauxRPC will automatically catch the error and fall back to serving a mock response (from stubs or random fake generation). This allows frontend and backend teams to co-develop APIs incrementally.

Generating Invalid Data

By default FauxRPC honors the protovalidate rules on a schema, so generated data passes validation. --violate-rules inverts that for testing how clients handle bad data: it takes a probability from 0.0 to 1.0 that any single rule is broken instead of satisfied.

# break every rule that can be broken
fauxrpc run --schema=service.binpb --violate-rules=1.0

# break roughly one rule in five
fauxrpc generate --schema=service.binpb --target=pkg.v1.Response --violate-rules=0.2

The same option is available on fauxrpc run, fauxrpc generate, and fauxrpc curl.

The dice are rolled per rule, not per field or per message. A field carrying a single rule is invalid about p of the time; a field carrying three independent rules is invalid about 1-(1-p)³ of the time. Because a field can only hold one value, when several of its rules come up at once one of them is picked at random to be the one that breaks — so repeated runs exercise different failure modes: a string with both min_len and pattern is sometimes too short and sometimes malformed. required counts as a rule of its own, broken by leaving the field unset.

A few things are never violated, so a message is not guaranteed to fail validation even at 1.0:

  • Fields with no rules, or with ignore: IGNORE_ALWAYS.
  • Message-level rules and CEL expressions (cel, cel_expression), which no single field value can be reasoned about generically.
  • Rules where no counterexample exists, such as an int32 bounded by gte at the type's minimum.

Generating Extension Fields

A message that reserves an extension range lends those field numbers to fields declared elsewhere:

message Event {
  string id = 1;
  string type = 2;

  extensions 100 to 199;
}

extend Event {
  string trace_id = 100;
  bool sampled = 101;
}

Those fields are part of the schema, so FauxRPC fills them in like any other field. Each one gets its own roll, so about half of a message's extensions are set on any given response and no two responses carry quite the same set — an extension is an add-on, and a message where every add-on is present is not what clients see in practice.

In JSON, an extension appears under its full name in brackets:

{
  "id": "evt_7f3a91",
  "type": "checkout.completed",
  "[playground.v1.trace_id]": "b9c14e2d",
  "[playground.v1.sampled]": true
}

Extensions of the google.protobuf.*Options messages are skipped. Every custom option in a schema is one of those, and they describe a schema rather than carry data.

Stubs may name extensions in the same bracketed form.

Making Requests with fauxrpc curl

FauxRPC includes a handy built-in client, fauxrpc curl, for making requests to your services without needing external tools. It automatically sources the schema to provide a seamless testing experience.

Hit all RPCs in a service with default data
fauxrpc curl --http2-prior-knowledge --schema=buf.build/bufbuild/registry
Hit a specific RPC
fauxrpc curl --http2-prior-knowledge --schema=buf.build/bufbuild/registry buf.registry.plugin.v1beta1.LabelService/ListLabels
Using server reflection

If no --schema option is provided, server reflection will be used to figure out the type and service information.

fauxrpc curl --http2-prior-knowledge buf.registry.plugin.v1beta1.LabelService/ListLabels

Dashboard

Enhance your FauxRPC experience with the interactive dashboard, providing real-time insights into your server's operations.

To enable the dashboard, simply start FauxRPC with the --dashboard option:

fauxrpc run --schema=service.binpb --dashboard

Access the dashboard in your browser at http://127.0.0.1:6660/fauxrpc.

The dashboard provides:

  • 📊 Summary: View overall server statistics.
  • 📜 Request Log: Live stream of all incoming requests.
  • 📁 Schema Browser: Explore Protobuf schemas loaded into the server.
  • 🔌 Stubs: Manage and view details of registered stubs.
  • 📚 API Documentation: Access generated Protobuf documentation and interactive OpenAPI documentation.

Go to the documentation website for more!

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotFaked = errors.New("no data was faked either because there was no relevant data or the faker was just out of faker juice")
)

Functions

func Bool added in v0.0.9 

func Bool(fd protoreflect.FieldDescriptor, opts GenOptions) bool

Bool returns a fake boolean value given a field descriptor.

func Bytes added in v0.0.9 

func Bytes(fd protoreflect.FieldDescriptor, opts GenOptions) []byte

Bytes returns a fake []byte value given a field descriptor.

func Enum added in v0.0.9 

func Enum(fd protoreflect.FieldDescriptor, opts GenOptions) protoreflect.EnumNumber

func FieldValue added in v0.3.0 

func FieldValue(fd protoreflect.FieldDescriptor, opts GenOptions) *protoreflect.Value

func Fixed32 added in v0.0.9 

func Fixed32(fd protoreflect.FieldDescriptor, opts GenOptions) uint32

Fixed32 returns a fake fixed32 value given a field descriptor.

func Fixed64 added in v0.0.9 

func Fixed64(fd protoreflect.FieldDescriptor, opts GenOptions) uint64

Fixed64 returns a fake fixed64 value given a field descriptor.

func Float32 added in v0.0.9 

func Float32(fd protoreflect.FieldDescriptor, opts GenOptions) float32

Float32 returns a fake float32 value given a field descriptor.

func Float64 added in v0.0.9 

func Float64(fd protoreflect.FieldDescriptor, opts GenOptions) float64

Float64 returns a fake float64 value given a field descriptor.

func GoogleDuration added in v0.0.9 

func GoogleDuration(fd protoreflect.FieldDescriptor, opts GenOptions) *durationpb.Duration

GoogleDuration generates a random google.protobuf.Duration value.

func GoogleFieldMask added in v0.28.0 

func GoogleFieldMask(fd protoreflect.FieldDescriptor, opts GenOptions) *fieldmaskpb.FieldMask

GoogleFieldMask generates a random google.protobuf.FieldMask value.

A field mask is only meaningful relative to some other message: its paths have to name fields that actually exist, or the mask is useless to whatever reads it. So the message the mask most likely applies to is guessed from the mask's surroundings (see fieldMaskTarget) and paths are drawn from that message's fields.

func GoogleTimestamp added in v0.0.9 

func GoogleTimestamp(fd protoreflect.FieldDescriptor, opts GenOptions) *timestamppb.Timestamp

GoogleTimestamp generates a random google.protobuf.Timestamp value.

func GoogleValue added in v0.0.9 

func GoogleValue(fd protoreflect.FieldDescriptor, opts GenOptions) *structpb.Value

func Int32 added in v0.0.9 

func Int32(fd protoreflect.FieldDescriptor, opts GenOptions) int32

Int32 returns a fake int32 value given a field descriptor.

func Int64 added in v0.0.9 

func Int64(fd protoreflect.FieldDescriptor, opts GenOptions) int64

Int64 returns a fake int64 value given a field descriptor.

func Map added in v0.0.16 

func Map(msg protoreflect.Message, fd protoreflect.FieldDescriptor, opts GenOptions) *protoreflect.Value

Map returns a fake repeated value given a field descriptor.

func NewFauxFaker added in v0.3.0 

func NewFauxFaker() *fauxFaker

func NewMessage added in v0.0.10 

func NewMessage(md protoreflect.MessageDescriptor, opts GenOptions) (protoreflect.ProtoMessage, error)

NewMessage creates a new message populated with fake data given a protoreflect.MessageDescriptor

Example 
package main

import (
	"fmt"

	elizav1 "buf.build/gen/go/connectrpc/eliza/protocolbuffers/go/connectrpc/eliza/v1"
	"github.com/sudorandom/fauxrpc"
	"google.golang.org/protobuf/encoding/protojson"
)

func main() {
	msg, _ := fauxrpc.NewMessage(elizav1.File_connectrpc_eliza_v1_eliza_proto.Messages().ByName("SayResponse"), fauxrpc.GenOptions{})
	b, _ := protojson.MarshalOptions{Indent: "  "}.Marshal(msg)
	fmt.Println(string(b))
}

func NewMultiFaker added in v0.3.0 

func NewMultiFaker(fakers []ProtoFaker) multiFaker

func Repeated added in v0.0.16 

func Repeated(msg protoreflect.Message, fd protoreflect.FieldDescriptor, opts GenOptions) *protoreflect.Value

Repeated returns a fake repeated value given a field descriptor.

func SFixed32 added in v0.0.9 

func SFixed32(fd protoreflect.FieldDescriptor, opts GenOptions) int32

SFixed32 returns a fake sfixedint32 value given a field descriptor.

func SFixed64 added in v0.0.9 

func SFixed64(fd protoreflect.FieldDescriptor, opts GenOptions) int64

SFixed64 returns a fake sfixed64 value given a field descriptor.

func SInt32 added in v0.0.9 

func SInt32(fd protoreflect.FieldDescriptor, opts GenOptions) int32

SInt32 returns a fake sint32 value given a field descriptor.

func SInt64 added in v0.0.9 

func SInt64(fd protoreflect.FieldDescriptor, opts GenOptions) int64

SInt64 returns a fake sint64 value given a field descriptor.

func SetDataOnMessage added in v0.0.4 

func SetDataOnMessage(msg protoreflect.ProtoMessage, opts GenOptions) error

SetDataOnMessage generates fake data given a protoreflect.ProtoMessage and sets the field values.

Example 
package main

import (
	"fmt"
	"log"

	elizav1 "buf.build/gen/go/connectrpc/eliza/protocolbuffers/go/connectrpc/eliza/v1"
	"github.com/sudorandom/fauxrpc"
	"google.golang.org/protobuf/encoding/protojson"
)

func main() {
	msg := &elizav1.SayResponse{}
	if err := fauxrpc.SetDataOnMessage(msg, fauxrpc.GenOptions{}); err != nil {
		log.Fatalf("error: %s", err) // handle error
	}
	b, _ := protojson.MarshalOptions{Indent: "  "}.Marshal(msg)
	fmt.Println(string(b))
}

func String added in v0.0.9 

func String(fd protoreflect.FieldDescriptor, opts GenOptions) string

String returns a fake string value given a field descriptor.

func UInt32 added in v0.0.9 

func UInt32(fd protoreflect.FieldDescriptor, opts GenOptions) uint32

UInt32 returns a fake uint32 value given a field descriptor.

func UInt64 added in v0.0.9 

func UInt64(fd protoreflect.FieldDescriptor, opts GenOptions) uint64

UInt64 returns a fake uint64 value given a field descriptor.

func UninterpretedOption added in v0.6.0 

func UninterpretedOption(opts GenOptions) *descriptorpb.UninterpretedOption

UninterpretedOption generates a random google.protobuf.UninterpretedOption value.

Types

type ExtensionResolver added in v0.28.0 

type ExtensionResolver interface {
	RangeExtensionsByMessage(message protoreflect.FullName, f func(protoreflect.ExtensionType) bool)
}

ExtensionResolver hands back the extensions declared for a message. It is the part of *protoregistry.Types that generation needs, and both protoregistry.GlobalTypes and a registry built from a loaded schema satisfy it.

type FieldGenOptions added in v0.6.0 

type FieldGenOptions struct {
	Message *validate.FieldRules
}

type GenOptions added in v0.0.14 

type GenOptions struct {
	MaxDepth     int
	Faker        *gofakeit.Faker
	Context      context.Context
	StubRecorder func(StubEntry)
	StubFinder   StubFinder

	// ViolateRules is the probability, from 0.0 to 1.0, that any single
	// protovalidate rule is broken rather than satisfied. Every rule on every
	// field is rolled independently, so a field carrying five rules is far more
	// likely to end up invalid than a field carrying one. 0 (the default) never
	// violates and 1 breaks every rule it can.
	//
	// A field can only hold one value, so when several of its rules come up at
	// once, one of them is picked at random to be the one that breaks.
	//
	// Rules that no value can violate on its own (message-level rules and CEL
	// expressions) are always satisfied, so a message is not guaranteed to fail
	// validation even at 1.0.
	ViolateRules float64

	// Extensions is where generation looks for the extensions of each message
	// it fills in. It has no default: a message descriptor cannot name the
	// extensions declared against it, so without a resolver to ask, extension
	// fields are left unset.
	//
	// A registry that loaded the schema is the resolver to pass; for types
	// compiled into the binary, protoregistry.GlobalTypes works.
	Extensions ExtensionResolver
	// contains filtered or unexported fields
}

func (GenOptions) GetContext added in v0.3.0 

func (st GenOptions) GetContext() context.Context

func (GenOptions) WithExtraFieldConstraints added in v0.6.0 

func (st GenOptions) WithExtraFieldConstraints(rules *validate.FieldRules) GenOptions

type ProtoFaker added in v0.3.0 

type ProtoFaker interface {
	SetDataOnMessage(msg protoreflect.ProtoMessage, opts GenOptions) error
}

type StubEntry added in v0.5.0 

type StubEntry interface {
	GetName() protoreflect.FullName
	GetID() string
}

type StubFinder added in v0.17.0 

type StubFinder interface {
	FindStub(name protoreflect.FullName, faker *gofakeit.Faker) protoreflect.ProtoMessage
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
fauxrpc command
example
generated-faux-server module
generated-mocks module
private
engine
frontend
frontend/templates
templ: version: v0.3.1020
 templ: version: v0.3.1020
frontend/templates/browser
templ: version: v0.3.1020
 templ: version: v0.3.1020
frontend/templates/browser/partials
templ: version: v0.3.1020
 templ: version: v0.3.1020
frontend/templates/partials
templ: version: v0.3.1020
 templ: version: v0.3.1020
frontend/templates/stubs
templ: version: v0.3.1020
 templ: version: v0.3.1020
gen
gen/registry/v1
gen/registry/v1/registryv1connect
gen/stubs/v1
gen/stubs/v1/stubsv1connect
gen/test/v1
gen/test/v1/testv1connect
grpc
log
metrics
openapi
openapi/generator
registry
server
stub
stubs

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.