rpc

package
v0.0.29 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: MIT Imports: 29 Imported by: 6

Documentation

Index

Constants

View Source 
const (
	StatusOK      = 200
	StatusInvalid = 422
	StatusError   = 500
)

Variables

This section is empty.

Functions

func DefaultDocsHTML 

func DefaultDocsHTML(openAPIPath string) string

DefaultDocsHTML returns the integrated docs/admin UI HTML.

func WriteDocsHTMLFile 

func WriteDocsHTMLFile(path, openAPIPath string) error

WriteDocsHTMLFile writes the default docs HTML to the path provided.

Types

type AdvancedObservabilityOption added in v0.0.28 

type AdvancedObservabilityOption func(*AdvancedObservabilityOptions)

AdvancedObservabilityOption mutates AdvancedObservabilityOptions.

func WithObservabilitySampling added in v0.0.28 

func WithObservabilitySampling(rate float64) AdvancedObservabilityOption

WithObservabilitySampling overrides the advanced trace sampling rate.

type AdvancedObservabilityOptions added in v0.0.28 

type AdvancedObservabilityOptions struct {
	SampleRate float64
}

AdvancedObservabilityOptions configures advanced in-memory tracking.

type DBExplorer added in v0.0.28 

type DBExplorer interface {
	State(context.Context) (DBExplorerState, error)
	PreviewTable(context.Context, DBPreviewInput) (DBQueryResult, error)
	RunQuery(context.Context, DBRunQueryInput) (DBQueryResult, error)
}

DBExplorer exposes read-only schema discovery and query execution for admin UI use.

func NewPGXDBExplorer added in v0.0.28 

func NewPGXDBExplorer(pool *pgxpool.Pool, opts ...DBExplorerOption) DBExplorer

NewPGXDBExplorer returns a pgxpool-backed read-only explorer.

func NewSQLDBExplorer added in v0.0.28 

func NewSQLDBExplorer(db *sql.DB, opts ...DBExplorerOption) DBExplorer

NewSQLDBExplorer returns a database/sql-backed read-only explorer.

type DBExplorerOption added in v0.0.28 

type DBExplorerOption func(*DBExplorerOptions)

DBExplorerOption mutates DBExplorerOptions.

func WithDBExplorerMaxRows added in v0.0.28 

func WithDBExplorerMaxRows(maxRows int) DBExplorerOption

WithDBExplorerMaxRows overrides the hard row cap for ad hoc queries.

func WithDBExplorerPreviewRows added in v0.0.28 

func WithDBExplorerPreviewRows(previewRows int) DBExplorerOption

WithDBExplorerPreviewRows overrides the default preview table row count.

func WithDBExplorerSystemSchemas added in v0.0.28 

func WithDBExplorerSystemSchemas(enabled bool) DBExplorerOption

WithDBExplorerSystemSchemas includes engine-owned schemas in discovery results.

func WithDBExplorerTimeout added in v0.0.28 

func WithDBExplorerTimeout(timeout time.Duration) DBExplorerOption

WithDBExplorerTimeout overrides the query timeout.

type DBExplorerOptions added in v0.0.28 

type DBExplorerOptions struct {
	Timeout              time.Duration
	MaxRows              int
	PreviewRows          int
	DefaultQueryRows     int
	IncludeSystemSchemas bool
}

DBExplorerOptions configures a DB explorer backend.

type DBExplorerState added in v0.0.28 

type DBExplorerState struct {
	Dialect     string       `json:"dialect"`
	TimeoutMS   int64        `json:"timeoutMs"`
	MaxRows     int          `json:"maxRows"`
	PreviewRows int          `json:"previewRows"`
	Schemas     []DBSchema   `json:"schemas"`
	Source      DBSourceInfo `json:"source"`
}

DBExplorerState is the payload rendered by the admin database explorer.

type DBPreviewInput added in v0.0.28 

type DBPreviewInput struct {
	Schema string `json:"schema"`
	Table  string `json:"table"`
	Limit  int    `json:"limit,omitempty"`
}

DBPreviewInput identifies a table preview request.

type DBQueryColumn added in v0.0.28 

type DBQueryColumn struct {
	Name         string `json:"name"`
	DatabaseType string `json:"databaseType,omitempty"`
}

DBQueryColumn describes one column in a result set.

type DBQueryResult added in v0.0.28 

type DBQueryResult struct {
	Query       string          `json:"query"`
	ExecutionMS int64           `json:"executionMs"`
	RowCount    int             `json:"rowCount"`
	Columns     []DBQueryColumn `json:"columns"`
	Rows        [][]any         `json:"rows"`
	Error       string          `json:"error,omitempty"`
}

DBQueryResult is the tabular query response for previews and ad hoc queries.

type DBRunQueryInput added in v0.0.28 

type DBRunQueryInput struct {
	Query string `json:"query"`
	Limit int    `json:"limit,omitempty"`
}

DBRunQueryInput contains one ad hoc read-only query.

type DBSchema added in v0.0.28 

type DBSchema struct {
	Name       string    `json:"name"`
	TableCount int       `json:"tableCount"`
	Tables     []DBTable `json:"tables"`
}

DBSchema describes one schema and its tables.

type DBSourceInfo added in v0.0.28 

type DBSourceInfo struct {
	Connection string `json:"connection"`
	ReadOnly   bool   `json:"readOnly"`
}

DBSourceInfo describes how the explorer is attached.

type DBTable added in v0.0.28 

type DBTable struct {
	Schema      string `json:"schema"`
	Name        string `json:"name"`
	Type        string `json:"type"`
	RowEstimate *int64 `json:"rowEstimate,omitempty"`
}

DBTable describes one table or view in the explorer tree.

type DocOpt 

type DocOpt func(*DocsOptions)

DocOpt mutates DocsOptions.

func WithDocsFile 

func WithDocsFile(path string) DocOpt

WithDocsFile overrides the docs HTML file path.

func WithDocsPath 

func WithDocsPath(path string) DocOpt

WithDocsPath overrides the docs base path.

func WithModules added in v0.0.28 

func WithModules(modules ...Module) DocOpt

WithModules enables the docs modules shown in the UI.

func WithOpenAPIFile 

func WithOpenAPIFile(path string) DocOpt

WithOpenAPIFile overrides the OpenAPI spec file path.

func WithOpenAPIPath 

func WithOpenAPIPath(path string) DocOpt

WithOpenAPIPath overrides the OpenAPI route path.

func WithSQLRoot added in v0.0.24 

func WithSQLRoot(path string) DocOpt

WithSQLRoot sets the root folder scanned for db/sql schema and query files.

type DocsOptions 

type DocsOptions struct {
	DocsPath    string
	DocsFile    string
	OpenAPIPath string
	OpenAPIFile string
	SQLRoot     string
	Modules     []Module
	// contains filtered or unexported fields
}

DocsOptions configures docs and OpenAPI routes.

type Guard 

type Guard = guard.Guard

Guard carries auth metadata and middleware for a route.

type GuardSpec 

type GuardSpec = guard.Spec

GuardSpec describes how to inject auth for a route.

type Module added in v0.0.28 

type Module string

Module identifies one top-level docs console module. 

const (
	ModuleAPI           Module = "api"
	ModuleDatabase      Module = "database"
	ModuleObservability Module = "observability"
)

type OpenAPIContact 

type OpenAPIContact struct {
	Name  string
	URL   string
	Email string
}

OpenAPIContact provides contact info for the API.

type OpenAPIExternalDocs 

type OpenAPIExternalDocs struct {
	Description string `json:"description,omitempty"`
	URL         string `json:"url"`
}

OpenAPIExternalDocs provides a link to external documentation.

type OpenAPILicense 

type OpenAPILicense struct {
	Name string
	URL  string
}

OpenAPILicense provides license info for the API.

type OpenAPIOptions 

type OpenAPIOptions struct {
	Title        string
	Version      string
	Description  string
	Servers      []OpenAPIServer
	Tags         []OpenAPITag
	Contact      *OpenAPIContact
	License      *OpenAPILicense
	ExternalDocs *OpenAPIExternalDocs
}

OpenAPIOptions controls top-level OpenAPI document metadata.

type OpenAPIServer 

type OpenAPIServer struct {
	URL         string
	Description string
}

OpenAPIServer describes a server entry in the OpenAPI document.

type OpenAPITag 

type OpenAPITag struct {
	Name        string
	Description string
}

OpenAPITag describes a top-level OpenAPI tag.

type Route 

type Route struct {
	Path         string
	Service      string
	Method       string
	RequestType  reflect.Type
	ResponseType reflect.Type
	Guards       []GuardSpec
}

Route captures a registered RPC handler and its metadata.

type Router 

type Router struct {
	// contains filtered or unexported fields
}

Router registers RPC handlers and exposes documentation metadata.

func NewRouter 

func NewRouter(opts ...RouterOption) *Router

NewRouter returns a new Router.

func (*Router) AttachLogger added in v0.0.24 

func (r *Router) AttachLogger(next http.Handler) http.Handler

AttachLogger wraps next with request-event capture for docs live logging.

Call this once at the top-level mux/handler boundary for all-or-nothing logging. If next is nil, the router itself is wrapped.

func (*Router) DocsHandler added in v0.0.28 

func (r *Router) DocsHandler(opts ...DocOpt) http.Handler

DocsHandler returns a mountable docs/admin handler with subtree-local endpoints.

func (*Router) HandleRPC 

func (r *Router) HandleRPC(fn any, guards ...Guard)

HandleRPC registers a typed RPC handler.

func (*Router) OpenAPI 

func (r *Router) OpenAPI() ([]byte, error)

OpenAPI generates an OpenAPI 3.0 document for the registered RPC routes.

func (*Router) Routes 

func (r *Router) Routes() []Route

Routes returns a snapshot of registered routes with metadata.

func (*Router) ServeAllDocs 

func (r *Router) ServeAllDocs(opts ...ServeAllDocsOpt)

ServeAllDocs registers docs, OpenAPI, and client routes on the router.

func (*Router) ServeClientJS 

func (r *Router) ServeClientJS(w http.ResponseWriter, _ *http.Request)

ServeClientJS writes a runtime-generated JS client as an HTTP response.

func (*Router) ServeClientJSHash 

func (r *Router) ServeClientJSHash(w http.ResponseWriter, _ *http.Request)

ServeClientJSHash writes the hash of the JS client as an HTTP response.

func (*Router) ServeClientPY 

func (r *Router) ServeClientPY(w http.ResponseWriter, _ *http.Request)

ServeClientPY writes a runtime-generated Python client as an HTTP response.

func (*Router) ServeClientPYHash 

func (r *Router) ServeClientPYHash(w http.ResponseWriter, _ *http.Request)

ServeClientPYHash writes the hash of the Python client as an HTTP response.

func (*Router) ServeClientTS 

func (r *Router) ServeClientTS(w http.ResponseWriter, _ *http.Request)

ServeClientTS writes a runtime-generated TS client as an HTTP response.

func (*Router) ServeClientTSHash 

func (r *Router) ServeClientTSHash(w http.ResponseWriter, _ *http.Request)

ServeClientTSHash writes the hash of the TS client as an HTTP response.

func (*Router) ServeDocs 

func (r *Router) ServeDocs(opts ...DocOpt)

ServeDocs registers default docs and OpenAPI routes on the router.

func (*Router) ServeHTTP 

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler.

func (*Router) SetLogger 

func (r *Router) SetLogger(logger *slog.Logger)

SetLogger overrides the logger used for warnings.

func (*Router) SetOpenAPIOptions 

func (r *Router) SetOpenAPIOptions(opts OpenAPIOptions)

SetOpenAPIOptions replaces the OpenAPI document settings.

func (*Router) SetTypeOverrides 

func (r *Router) SetTypeOverrides(overrides map[string]TypeOverride)

SetTypeOverrides replaces the current type overrides used for client and OpenAPI generation.

func (*Router) WriteClientJS 

func (r *Router) WriteClientJS(w io.Writer) error

WriteClientJS writes a runtime-generated JS client to w.

func (*Router) WriteClientJSFile 

func (r *Router) WriteClientJSFile(path string) error

WriteClientJSFile writes a runtime-generated JS client to the file at path.

func (*Router) WriteClientJSHash 

func (r *Router) WriteClientJSHash(w io.Writer) error

WriteClientJSHash writes the hash of the JS client output to w.

func (*Router) WriteClientPY 

func (r *Router) WriteClientPY(w io.Writer) error

WriteClientPY writes a runtime-generated Python client to w.

func (*Router) WriteClientPYFile 

func (r *Router) WriteClientPYFile(path string) error

WriteClientPYFile writes a runtime-generated Python client to the file at path.

func (*Router) WriteClientPYHash 

func (r *Router) WriteClientPYHash(w io.Writer) error

WriteClientPYHash writes the hash of the Python client output to w.

func (*Router) WriteClientTS 

func (r *Router) WriteClientTS(w io.Writer) error

WriteClientTS writes a runtime-generated TS client to w.

func (*Router) WriteClientTSFile 

func (r *Router) WriteClientTSFile(path string) error

WriteClientTSFile writes a runtime-generated TS client to the file at path.

func (*Router) WriteClientTSHash 

func (r *Router) WriteClientTSHash(w io.Writer) error

WriteClientTSHash writes the hash of the TS client output to w.

func (*Router) WriteOpenAPIFile 

func (r *Router) WriteOpenAPIFile(path string) error

WriteOpenAPIFile writes the OpenAPI JSON output to the file at path.

type RouterOption 

type RouterOption func(*RouterOptions)

RouterOption mutates RouterOptions.

func WithAdvancedObservability added in v0.0.28 

func WithAdvancedObservability(opts ...AdvancedObservabilityOption) RouterOption

WithAdvancedObservability enables error grouping, guard metrics, and trace sampling.

func WithDBExplorer added in v0.0.28 

func WithDBExplorer(explorer DBExplorer) RouterOption

WithDBExplorer attaches a live database explorer to the router.

func WithGuards 

func WithGuards(guards ...Guard) RouterOption

WithGuards applies guards to every RPC handler registered on the router.

func WithPrefix 

func WithPrefix(prefix string) RouterOption

WithPrefix sets the base path prefix for RPC handlers.

type RouterOptions 

type RouterOptions struct {
	Prefix                string
	Guards                []Guard
	AdvancedObservability *AdvancedObservabilityOptions
	DBExplorer            DBExplorer
}

RouterOptions configures a Router.

type ServeAllDocsOpt 

type ServeAllDocsOpt func(*ServeAllDocsOptions)

ServeAllDocsOpt mutates ServeAllDocsOptions.

func WithClientJSPath 

func WithClientJSPath(path string) ServeAllDocsOpt

WithClientJSPath overrides the JS client route path.

func WithClientPYPath 

func WithClientPYPath(path string) ServeAllDocsOpt

WithClientPYPath overrides the Python client route path.

func WithClientTSPath 

func WithClientTSPath(path string) ServeAllDocsOpt

WithClientTSPath overrides the TS client route path.

func WithDocsOptions 

func WithDocsOptions(opts ...DocOpt) ServeAllDocsOpt

WithDocsOptions applies options for docs/OpenAPI routes.

func WithoutDocs 

func WithoutDocs() ServeAllDocsOpt

WithoutDocs disables docs/OpenAPI route registration.

type ServeAllDocsOptions 

type ServeAllDocsOptions struct {
	DocsEnabled  bool
	DocsOptions  []DocOpt
	ClientJSPath string
	ClientTSPath string
	ClientPYPath string
}

ServeAllDocsOptions configures ServeAllDocs behavior.

type TypeOverride 

type TypeOverride = schema.TypeOverride

TypeOverride customizes how a Go type is rendered for clients and OpenAPI.

Source Files

View all Source files

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.