fauxrpc

package module
v0.19.5 Latest Latest
Warning

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

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

README

FauxRPC

Go Go Report Card Go Reference

FauxRPC is a powerful tool that empowers you to accelerate development and testing by effortlessly generating fake implementations of gRPC, gRPC-Web, Connect, and REST services. If you have a protobuf-based workflow, this tool could help.

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).
  • 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: Test data from FauxRPC will try to automatically follow any protovalidate constraints that are defined.
  • Request Validation: Ensure data integrity with automatic request validation using protovalidate. Catch errors early and prevent invalid data from reaching your application logic.

See the the documentation website for more!

Get Started

Install via source
go install github.com/sudorandom/fauxrpc/cmd/[email protected]
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 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 Protobuf descriptors so FauxRPC knows which services to fake. Schemas can be loaded from multiple sources, and you can mix and match them.

From a local file:
fauxrpc run --schema=service.binpb
From the Buf Schema Registry (BSR)
fauxrpc run --schema=buf.build/bufbuild/eliza
From multiple sources at once
fauxrpc run --schema=service.binpb --schema=buf.build/bufbuild/eliza

Using Stubs

While FauxRPC generates random fake data by default, stubs let you define specific, predictable responses for your RPCs. This is great for testing specific scenarios.

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

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/

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 all Protobuf schemas loaded into the server.
  • 🔌 Stubs: Manage and view details of registered stubs.
  • 📚 API Documentation: Access auto-generated API 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 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 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
	// 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
frontend
frontend/templates
templ: version: v0.3.960
 templ: version: v0.3.960
frontend/templates/browser
templ: version: v0.3.960
 templ: version: v0.3.960
frontend/templates/browser/partials
templ: version: v0.3.960
 templ: version: v0.3.960
frontend/templates/partials
templ: version: v0.3.960
 templ: version: v0.3.960
frontend/templates/stubs
templ: version: v0.3.960
 templ: version: v0.3.960
gen/registry/v1
gen/registry/v1/registryv1connect
gen/stubs/v1
gen/stubs/v1/stubsv1connect
gen/test/v1
grpc
log
metrics
registry
server
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.