tailsql

type DBOptions struct {
	// Label is a human-readable descriptive label to show to users when
	// rendering this database in a UI.
	Label string

	// NamedQueries is a map from names to SQL query text, that the service
	// should allow as pre-defined queries for this database.
	//
	// Unlike user-saved queries, named queries allow the database to change the
	// query when the underlying schema changes while preserving the semantics
	// the user observes.
	NamedQueries map[string]string
}

type DBSpec struct {
	Source string `json:"source"`           // UI slug (required)
	Label  string `json:"label,omitempty"`  // descriptive label
	Driver string `json:"driver,omitempty"` // e.g., "sqlite", "snowflake"

	// Named is an optional map of named SQL queries the database should expose.
	Named map[string]string `json:"named,omitempty"`

	URL     string    `json:"url,omitempty"`     // path or connection URL
	KeyFile string    `json:"keyFile,omitempty"` // path to key file
	Secret  string    `json:"secret,omitempty"`  // name of secret
	DB      Queryable `json:"-"`                 // programmatic data source
}

type Duration time.Duration

type LocalClient interface {
	WhoIs(context.Context, string) (*apitype.WhoIsResponse, error)
}

type Options struct {
	// The tailnet hostname the server should run on (tsnet).
	Hostname string `json:"hostname,omitempty"`

	// The directory for tailscale state and configurations (tsnet).
	StateDir string `json:"stateDir,omitempty"`

	// If true, serve HTTPS instead of HTTP (tsnet).
	ServeHTTPS bool `json:"serveHTTPS,omitempty"`

	// The URL of the coordination server to use (tsnet).
	// If empty, the Tailscale default is used.
	ControlURL string `json:"controlURL,omitempty"`

	// If non-empty, a SQLite database URL to use for local state.
	LocalState string `json:"localState,omitempty"`

	// If non-empty, and LocalState is defined, export a read-only copy of the
	// local state database as a source with this name.
	LocalSource string `json:"localSource,omitempty"`

	// Databases that the server will allow queries against (optional).
	Sources []DBSpec `json:"sources,omitempty"`

	// Additional links that should be propagated to the UI.
	UILinks []UILink `json:"links,omitempty"`

	// If set, prepend this prefix to each HTTP route. By default, routes are
	// anchored at "/".
	RoutePrefix string `json:"routePrefix,omitempty"`

	// The maximum timeout for a database query (0 means no timeout).
	QueryTimeout Duration `json:"queryTimeout,omitempty"`

	// A connection to tailscaled for authorization checks. If nil, no
	// authorization checks are performed and all requests are permitted.
	LocalClient LocalClient `json:"-"`

	// If non-nil, the server will add metrics to this map. The caller is
	// responsible for ensuring the map is published.
	Metrics *expvar.Map `json:"-"`

	// If non-nil and a LocalClient is available, Authorize is called for each
	// request giving the requested database src and the caller's WhoIs record.
	// If it reports an error, the request is failed.
	//
	// If Authorize is nil and a LocalClient is available, the default rule is
	// to accept any logged-in user, rejecting tagged nodes.
	//
	// If no LocalClient is available, this field is ignored, no authorization
	// checks are performed, and all requests are accepted.
	Authorize func(src string, info *apitype.WhoIsResponse) error `json:"-"`

	// If non-nil, use this store to fetch secret values. This is required if
	// any of the sources specifies a named secret for its connection string.
	SecretStore *setec.Store `json:"-"`

	// Optional rules to apply when rendering text for presentation in the UI.
	// After generating the value string, each rule is matched in order, and the
	// first match (if any) is applied to rewrite the output. The value returned
	// by the rule replaces the original string.
	UIRewriteRules []UIRewriteRule `json:"-"`

	// If non-nil, call this function with each query presented to the API.  If
	// the function reports an error, the query fails; otherwise the returned
	// query state is used to service the query.  If nil, DefaultCheckQuery is
	// used.
	CheckQuery func(Query) (Query, error) `json:"-"`

	// If non-nil, send logs to this logger. If nil, use log.Printf.
	Logf logger.Logf `json:"-"`
}

type Query struct {
	Source string // the data source requested
	Query  string // the text of the query
}

type Queryable interface {
	// Query issues the specified SQL query in a transaction and returns the
	// matching result set, if any.
	Query(ctx context.Context, sql string, params ...any) (RowSet, error)

	// Close closes the database.
	Close() error
}

type RowSet interface {
	// Columns reports the names of the columns requested by the query.
	Columns() ([]string, error)

	// Close closes the row set, preventing further enumeration.
	Close() error

	// Err returns the error, if any, that was encountered during iteration.
	Err() error

	// Next prepares the next result row for reading by the Scan method, and
	// reports true if this was successful or false if there was an error or no
	// more rows are available.
	Next() bool

	// Scan copies the columns of the currently-selected row into the values
	// pointed to by its arguments.
	Scan(...any) error
}

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

type UILink struct {
	Anchor string `json:"anchor"`
	URL    string `json:"url"`
}

type UIRewriteRule struct {
	Column *regexp.Regexp // pattern for the column name (nil matches all)
	Value  *regexp.Regexp // pattern for the value (nil matches all)

	// The Apply function takes the name of a column, the input value, and the
	// result of matching the value regexp (if any). Its return value replaces
	// the input when the value is rendered. If Apply == nil, the input is not
	// modified.
	//
	// As a special case, if Apply returns a nil value, the rule evaluator skips
	// the rule as if it had not matched, and goes on to the next rule.
	Apply func(column, input string, valueMatch []string) any
}