serve

type Caller struct {
	// Name is what the audit line carries. It reaches a JSON document and
	// somebody's grep, so it is checked at boot rather than escaped later.
	Name string

	// Token is the bearer this caller presents.
	Token string
}

type Options struct {
	// Env decides whether an unauthenticated service may exist. It comes from
	// BREVIS_ENV and NEVER from a configuration file -- the gateway's rule,
	// and its reason: "a config file that could declare itself local would be
	// a file that turns off authentication."
	Env string

	// Token is the bearer every request must carry, with NO NAME attached.
	// Required outside local unless Callers names one.
	//
	// It is what every deployment has today and it keeps working. Its audit
	// lines carry no caller, which is itself the finding: a shared secret
	// with nobody's name on it.
	Token string

	// Callers are named bearers, and the audit line carries whichever one
	// asked. See caller.go for why identity is the credential rather than a
	// header. Folded together with Token into one list at boot.
	Callers []Caller

	// Addr is where this will listen, and it is EVIDENCE rather than
	// configuration: see New. Empty means nobody is deploying anything --
	// a test, or something embedding this -- and no rule is drawn from it.
	Addr string

	// Rows is the ceiling. A caller may ask for fewer and cannot ask for more.
	Rows int

	// Bytes is the most a single query may SCAN. A caller cannot raise it
	// and cannot name one at all: it is money, and the browser is not the
	// place that decides how much of it to spend.
	//
	// IT BOUNDS THE PREVIEW TOO, and that was a hole rather than a choice.
	// A preview is `SELECT * FROM t LIMIT 20`, and a LIMIT does not reduce
	// what BigQuery scans -- twenty rows off a petabyte table reads the
	// petabyte and bills for it. The row ceiling bounds the screen and
	// bounds nothing else.
	Bytes int64

	// Budget is the most one CONNECTION may scan in an hour, across every
	// query. Zero is no budget, which is the default.
	//
	// A CONCURRENCY LIMIT IS NOT A BUDGET -- CHECKPOINT B's F6. Four queries
	// at a time, each under the per-query ceiling, repeated forever, is
	// unbounded: the ceiling bounds one query and nothing bounds the sum.
	// For a single authenticated operator no budget may well be the right
	// answer, but it has to be a CHOICE, and an absence is not one. The boot
	// banner states whichever it is.
	//
	// PER CONNECTION, because a connection is what pays the bill: two
	// warehouses are two accounts, and exhausting one must not close the
	// other.
	//
	// IT BOUNDS WHAT IS METERED, which is not everything. A warehouse that
	// charges for a machine by the hour reports no bytes, so a budget bounds
	// BigQuery and bounds nothing on Postgres. That is fine -- Postgres is
	// not billed by the byte -- and dangerous only if somebody believes
	// otherwise, which is why the banner says which connections it can
	// actually bound.
	Budget int64

	// Writable NAMES THE CONNECTIONS on which a statement may write. Empty
	// is the default and is every deployment that has not asked otherwise.
	//
	// IT COMES FROM BREVIS_SQL_SERVE_WRITES AND NEVER FROM A FILE, which is
	// the rule Token already follows one field up and for the same reason: a
	// config file that could declare itself local would be a file that turns
	// off authentication, and one that could declare itself writable would
	// be a file that turns off every limit on this surface at once.
	//
	// NAMES AND NOT A BOOLEAN. One service reaches several warehouses, and
	// unlocking the one somebody develops against must not unlock the one
	// beside it. The accident this exists to prevent is a development
	// service that is also pointed at a production DSN, and a switch cannot
	// tell those apart.
	//
	// A NAME HERE STANDS DOWN EVERY LAYER AT ONCE -- the tokeniser, the
	// warehouse's verdict and the warehouse's enforcement -- so on a named
	// connection this service is exactly as powerful as its credential. The
	// row ceiling bounds a screen and the byte ceiling bounds MONEY; neither
	// bounds damage, because an UPDATE scans almost nothing and changes
	// everything.
	Writable []string

	// Audit is where one line per query goes. Nil writes none, which is what
	// a test wants and never what a deployment does.
	Audit io.Writer

	// Concurrent is how many queries may run at once. Over that, a caller is
	// REFUSED rather than queued: a queue behind a browser is a browser that
	// waits with no way to know why, and every waiting request still holds a
	// connection to the warehouse.
	Concurrent int

	// Timeout bounds one query, the dry run and the read together.
	Timeout time.Duration

	// Open connects to one warehouse. A field so a test can hand over a fake
	// without a warehouse, and so this package holds no driver of its own.
	//
	// IT TAKES THE WHOLE TARGET and not just a name, because a name is not
	// unique on its own: `app` can be a BigQuery project and a Postgres
	// database at once, and the registry matches on both halves.
	Open func(ctx context.Context, t Table) (dialect.Conn, error)
}

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

type Table struct {
	// Connection is which warehouse: the BigQuery project.
	Connection string
	// Dialect is whose SQL this is, which the classifier needs: `#` opens a
	// comment in one of them and is an operator in the other, and reading
	// the wrong one wrong is how `# SELECT\nDROP TABLE t` gets through.
	Dialect string
	// Relation is `dataset.table`, ready to be written into SQL -- which is
	// safe only because both halves matched `identifier`.
	Relation string
}