Documentation
¶
Overview ¶
Package server provides the HTTP API for Wadjet.
Index ¶
- type AdminAPI
- type AsyncQueryResponse
- type Config
- type CreateTableColumn
- type CreateTableRequest
- type GRPCConfig
- type GRPCServer
- func (g *GRPCServer) CancelQuery(ctx context.Context, req *wadjetv1.CancelQueryRequest) (*wadjetv1.CancelQueryResponse, error)
- func (g *GRPCServer) CreateTable(ctx context.Context, req *wadjetv1.CreateTableRequest) (*wadjetv1.CreateTableResponse, error)
- func (g *GRPCServer) DescribeTable(ctx context.Context, req *wadjetv1.DescribeTableRequest) (*wadjetv1.DescribeTableResponse, error)
- func (g *GRPCServer) DropTable(ctx context.Context, req *wadjetv1.DropTableRequest) (*wadjetv1.DropTableResponse, error)
- func (g *GRPCServer) GetQueryStatus(ctx context.Context, req *wadjetv1.GetQueryStatusRequest) (*wadjetv1.GetQueryStatusResponse, error)
- func (g *GRPCServer) ListTables(ctx context.Context, _ *wadjetv1.ListTablesRequest) (*wadjetv1.ListTablesResponse, error)
- func (g *GRPCServer) Query(ctx context.Context, req *wadjetv1.QueryRequest) (*wadjetv1.QueryResponse, error)
- func (g *GRPCServer) QueryStream(req *wadjetv1.QueryRequest, stream wadjetv1.WadjetService_QueryStreamServer) error
- func (g *GRPCServer) Shutdown()
- func (g *GRPCServer) Start() error
- func (g *GRPCServer) SubmitQuery(ctx context.Context, req *wadjetv1.QueryRequest) (*wadjetv1.SubmitQueryResponse, error)
- type OpsAPI
- type QueryRequest
- type QueryResponse
- type QueryStats
- type QueryStatusResponse
- type Server
- type StageStatusView
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AdminAPI ¶
type AdminAPI struct {
// contains filtered or unexported fields
}
AdminAPI provides REST endpoints for runtime configuration management. All admin endpoints require the "admin" permission.
func NewAdminAPI ¶
NewAdminAPI creates an admin API handler.
func (*AdminAPI) RegisterRoutes ¶
RegisterRoutes adds admin routes to the given router.
type AsyncQueryResponse ¶
type AsyncQueryResponse struct {
QueryID string `json:"query_id"`
State string `json:"state"`
Plan string `json:"plan,omitempty"`
}
AsyncQueryResponse is returned when a query is submitted asynchronously.
type Config ¶
type Config struct {
Addr string
Catalog *catalog.Catalog
Coordinator *coordinator.Coordinator // nil = local execution only
DLQ *coordinator.DLQ // nil = no DLQ (standalone mode)
Auth *auth.Authenticator // nil = no authentication (static mode)
Authz *auth.Authorizer // nil = no authorization (static mode)
Policies *auth.PolicySet // nil = no cell-level policies (static mode)
Provider *auth.Provider // nil = use static Auth/Authz/Policies above
Metrics *metrics.Metrics // nil = no metrics collection
TLSConfig *tls.Config // nil = plain HTTP
MaxConnections int // 0 = unlimited
SlowQueryThreshold time.Duration // 0 = disabled, log queries exceeding this
ShutdownTimeout time.Duration // graceful shutdown drain timeout (default 30s)
QueryLimits *config.QueryLimits // global cost-based query limits (nil = unlimited)
RoleLimits map[string]*config.QueryLimits // per-role overrides (nil = use global)
SortMergeJoinBytes int64 // local sort-merge-join gate (0 = disabled)
LateMaterialization bool // view-column join output, deferred gather (default off)
}
Config holds server configuration.
type CreateTableColumn ¶
type CreateTableColumn struct {
Name string `json:"name"`
Type string `json:"type"`
Nullable *bool `json:"nullable,omitempty"` // default true
}
CreateTableColumn defines a column in a REST table creation request.
type CreateTableRequest ¶
type CreateTableRequest struct {
Name string `json:"name"`
Columns []CreateTableColumn `json:"columns"`
PartitionKeys []string `json:"partition_keys,omitempty"`
}
CreateTableRequest is the request body for POST /v1/tables.
type GRPCConfig ¶
type GRPCConfig struct {
Addr string
Catalog *catalog.Catalog
Coord *coordinator.Coordinator // nil = standalone
DB *wadjetdb.DB // nil = distributed
TLSConfig *tls.Config // nil = plain gRPC
MaxConnections int // 0 = unlimited
AuthProvider *auth.Provider // nil = no auth enforcement
}
GRPCConfig holds configuration for the gRPC server.
type GRPCServer ¶
type GRPCServer struct {
wadjetv1.UnimplementedWadjetServiceServer
// contains filtered or unexported fields
}
GRPCServer implements the WadjetService gRPC API.
func NewGRPCServer ¶
func NewGRPCServer(cfg GRPCConfig, logger *slog.Logger) *GRPCServer
NewGRPCServer creates a new gRPC server.
func (*GRPCServer) CancelQuery ¶
func (g *GRPCServer) CancelQuery(ctx context.Context, req *wadjetv1.CancelQueryRequest) (*wadjetv1.CancelQueryResponse, error)
CancelQuery cancels a running query.
func (*GRPCServer) CreateTable ¶
func (g *GRPCServer) CreateTable(ctx context.Context, req *wadjetv1.CreateTableRequest) (*wadjetv1.CreateTableResponse, error)
CreateTable creates a new table.
func (*GRPCServer) DescribeTable ¶
func (g *GRPCServer) DescribeTable(ctx context.Context, req *wadjetv1.DescribeTableRequest) (*wadjetv1.DescribeTableResponse, error)
DescribeTable returns a table's schema to an identity that may read it.
Column names, types and the partition design are an exact target map, and this door handed them to any authenticated caller for any table (#935). The decision is the table's own — auth.TableAccess with ActionRead — so it agrees with what a SELECT on the same relation would be told, and it is taken BEFORE the catalog read: a refusal reveals nothing, not even whether the table is there.
The shape check comes first here, unlike the DDL RPCs: those ask a permission-only question that needs no request, while this one cannot decide anything without a table name.
func (*GRPCServer) DropTable ¶
func (g *GRPCServer) DropTable(ctx context.Context, req *wadjetv1.DropTableRequest) (*wadjetv1.DropTableResponse, error)
DropTable removes a table.
func (*GRPCServer) GetQueryStatus ¶
func (g *GRPCServer) GetQueryStatus(ctx context.Context, req *wadjetv1.GetQueryStatusRequest) (*wadjetv1.GetQueryStatusResponse, error)
GetQueryStatus returns the status of an async query.
func (*GRPCServer) ListTables ¶
func (g *GRPCServer) ListTables(ctx context.Context, _ *wadjetv1.ListTablesRequest) (*wadjetv1.ListTablesResponse, error)
ListTables returns the table names this identity may read.
The listing is filtered by the SAME decision that governs reading the table (auth.VisibleTables → auth.TableAccess), so a name an identity may not read is not published to it either. That is the product's position rather than PostgreSQL's — `\d` shows every relation to anyone — and it is the behavior the HTTP door already had (`FilterTables` on /v1/tables and SHOW TABLES) while this door published the whole catalog to any authenticated caller (#935). Explicit ABAC denies govern it, because the evaluator is what TableAccess asks whenever one is installed.
func (*GRPCServer) Query ¶
func (g *GRPCServer) Query(ctx context.Context, req *wadjetv1.QueryRequest) (*wadjetv1.QueryResponse, error)
Query executes a SQL query and returns all results.
func (*GRPCServer) QueryStream ¶
func (g *GRPCServer) QueryStream(req *wadjetv1.QueryRequest, stream wadjetv1.WadjetService_QueryStreamServer) error
QueryStream executes a SQL query and streams result batches.
func (*GRPCServer) Shutdown ¶
func (g *GRPCServer) Shutdown()
Shutdown gracefully stops the gRPC server.
func (*GRPCServer) Start ¶
func (g *GRPCServer) Start() error
Start begins serving gRPC on the configured address.
func (*GRPCServer) SubmitQuery ¶
func (g *GRPCServer) SubmitQuery(ctx context.Context, req *wadjetv1.QueryRequest) (*wadjetv1.SubmitQueryResponse, error)
SubmitQuery submits an async query (distributed mode only).
type OpsAPI ¶
type OpsAPI struct {
// contains filtered or unexported fields
}
OpsAPI provides operational endpoints for monitoring and cleanup.
Every route it registers requires the `admin` permission, the way the admin API's do: they read the cluster's operational state or destroy stored artifacts, and neither is something an ordinary query identity may do.
func NewOpsAPI ¶
func NewOpsAPI(coord *coordinator.Coordinator, provider *auth.Provider) *OpsAPI
NewOpsAPI creates operational API endpoints. The provider is what the routes authorize against; nil (or auth disabled) enforces nothing.
func (*OpsAPI) RegisterRoutes ¶
RegisterRoutes adds operational routes to the given router.
type QueryRequest ¶
type QueryRequest struct {
SQL string `json:"sql"`
}
QueryRequest is the request body for POST /v1/queries.
type QueryResponse ¶
type QueryResponse struct {
QueryID string `json:"query_id"`
Columns []string `json:"columns"`
Rows []map[string]any `json:"rows"`
// Values is the same rows POSITIONALLY, one slice per row aligned with
// Columns. It is sent whenever two output columns publish ONE NAME, which
// a JSON object cannot represent: `SELECT g + 1, g + 2, g + 3` is three
// columns called `?column?` in PostgreSQL and here (#732), and `rows`
// carries one key for the three of them. `columns` is always the full
// positional list; a client that needs every value reads `values` when it
// is present (round-1 review B1).
Values [][]any `json:"values,omitempty"`
Stats QueryStats `json:"stats"`
Error string `json:"error,omitempty"`
}
QueryResponse is the response for POST /v1/queries.
type QueryStats ¶
type QueryStats struct {
Elapsed string `json:"elapsed"`
RowsScanned int64 `json:"rows_scanned"`
Plan string `json:"plan,omitempty"`
}
QueryStats contains execution statistics.
type QueryStatusResponse ¶
type QueryStatusResponse struct {
QueryID string `json:"query_id"`
SQL string `json:"sql"`
State string `json:"state"`
Stages []StageStatusView `json:"stages,omitempty"`
Elapsed string `json:"elapsed"`
TotalRows int64 `json:"total_rows"`
Error string `json:"error,omitempty"`
}
QueryStatusResponse is returned when checking query status.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the Wadjet HTTP API server.
func (*Server) Mux ¶
Mux returns the underlying chi router for registering additional routes (e.g. admin API).
Directories
¶
| Path | Synopsis |
|---|---|
|
Package mcp implements a Model Context Protocol (MCP) server for Wadjet.
|
Package mcp implements a Model Context Protocol (MCP) server for Wadjet. |
|
Package pgwire implements the PostgreSQL v3 wire protocol frontend.
|
Package pgwire implements the PostgreSQL v3 wire protocol frontend. |