Documentation
¶
Overview ¶
Package postgres keeps the records of the API keys in PostgreSQL (ADR 0004), through jackc/pgx: their keyed digests, never the keys.
The schema is changed by versioned SQL migrations embedded in the binary and applied by Migrate, from the admin command with a role that may change it; the API, connected with a role that can only read and write the tables, never migrates. A connection beyond the local machine must verify the server's certificate and host name (sslmode=verify-full), and every query is bounded by queryTimeout on top of its context.
Index ¶
- Variables
- func Migrate(ctx context.Context, conn string) error
- func ParseConfig(conn string) (*pgxpool.Config, error)
- type KeyServices
- type Keys
- func (k *Keys) Close()
- func (k *Keys) CreateKey(ctx context.Context, r domain.KeyRecord) (domain.KeyRecord, error)
- func (k *Keys) FindKey(ctx context.Context, d domain.KeyDigest) (domain.KeyRecord, error)
- func (k *Keys) ListKeys(ctx context.Context) ([]domain.KeyRecord, error)
- func (k *Keys) PurgeRevokedKeys(ctx context.Context, cutoff time.Time) (int64, error)
- func (k *Keys) RevokeKey(ctx context.Context, id int64, at time.Time) error
Constants ¶
This section is empty.
Variables ¶
var ErrInsecure = errors.New("database connection without verified TLS")
ErrInsecure means a connection string lets a connection to a remote host go without TLS, or with TLS that does not verify the certificate and the host name: sslmode=verify-full is required beyond the local machine.
Functions ¶
func Migrate ¶
Migrate applies every migration not yet applied to the database of conn, one at a time under an advisory lock, so that two runs never interleave. It is run by the administration command with a role that may change the schema, never by the API on start (ADR 0004). Cancelling ctx stops it after the migration in progress.
func ParseConfig ¶
ParseConfig parses a PostgreSQL connection string, URL or key=value, and requires verified TLS (sslmode=verify-full) for every host but the local machine: a loopback address, "localhost" or a Unix socket. Its errors never quote the connection string, which may hold a password.
Types ¶
type KeyServices ¶ added in v0.51.0
type KeyServices struct {
// Auth accepts the active keys of the configured environment; a valid
// key is kept in memory for app.KeyCacheTTL.
Auth *app.Authenticator
// Purge deletes the keys revoked longer than
// domain.RevokedKeyRetention ago, every app.KeyPurgeEvery.
Purge *app.KeyPurge
// Close closes the database, waiting for the connections in use.
Close func()
}
KeyServices are the use cases of the API process on the API keys of the configured database, sharing one pool of connections.
func OpenKeyServices ¶ added in v0.51.0
OpenKeyServices returns the KeyServices of the configured database. The database is not reached until a key is checked or purged.
type Keys ¶
type Keys struct {
// contains filtered or unexported fields
}
Keys keeps the records of API keys in the api_keys table. It implements app.KeyFinder, app.KeyIssuer and app.KeyPurger.
func Open ¶
Open returns a Keys on the database of conn, which ParseConfig checks. It does not connect: the first query does, so the API starts and answers 503 while the database is unreachable.
func (*Keys) Close ¶
func (k *Keys) Close()
Close closes every connection, waiting for those in use.
func (*Keys) PurgeRevokedKeys ¶ added in v0.51.0
PurgeRevokedKeys deletes the keys revoked before cutoff and returns how many it deleted. Several instances may run it at once: each deletes what is left.
Source Files