database

package
v0.21.0 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: AGPL-3.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source
const ResultUnknown = "?"

ResultUnknown replaces any result Udash does not recognize.

View Source
const (
	URIEnvVariableName string = "UDASH_DB_URI"
)

Variables

ActionResults lists the results an action can be acknowledged with, worst first: failure, attention (changed), unknown, skipped, success.

View Source
var ErrAPITokenNotFound = errors.New("api token not found")

ErrAPITokenNotFound is returned when no token matches the request.

View Source
var (
	// ErrGCLocked is returned when another garbage collection is already running.
	ErrGCLocked = errors.New("another garbage collection is already running")
)
View Source
var ErrInvalidParameter = errors.New("invalid parameter")

ErrInvalidParameter is wrapped by the errors caused by the parameters of a request rather than by the database, so that the API can tell the caller what to fix while keeping every other error to itself.

View Source
var ErrSummaryRangeTooWide = errors.New("requested time range is too wide")

ErrSummaryRangeTooWide is returned when the requested time range spans more days than the caller allows. Callers are expected to turn it into a client error.

View Source
var ErrSummaryTooManyBuckets = errors.New("requested time range produces too many buckets")

ErrSummaryTooManyBuckets is returned when the requested time range and granularity would produce more buckets than the caller allows. Callers are expected to turn it into a client error.

Functions

func AcknowledgeAction added in v0.20.0

func AcknowledgeAction(ctx context.Context, url string, until time.Time, worstResult, by string) error

AcknowledgeAction hides an open action until the given time, or until its worst result differs from worstResult. Acknowledging an action again replaces the previous acknowledgement.

func Connect

func Connect(ctx context.Context, o Options) error

Connect opens the connection pool, and waits for the database to accept connections, retrying with backoff until ConnectTimeout or ctx expires.

func DeleteAPIToken added in v0.17.1

func DeleteAPIToken(ctx context.Context, id uuid.UUID, subject string) error

DeleteAPIToken removes a token. A non empty subject restricts the deletion to that subject's own tokens, so one identity cannot revoke another's.

func DeleteAPITokensBySubject added in v0.17.1

func DeleteAPITokensBySubject(ctx context.Context, subject string) (int64, error)

DeleteAPITokensBySubject removes every token of a subject, which is what offboarding an identity needs.

func DeleteConfigResource added in v0.10.0

func DeleteConfigResource(ctx context.Context, resourceType string, id string) error

DeleteConfigResource deletes a resource configuration from the database.

func DeleteReport added in v0.10.0

func DeleteReport(ctx context.Context, id string) error

DeleteReport deletes a report from the database.

func GetAPITokenByHash added in v0.17.1

func GetAPITokenByHash(ctx context.Context, tokenHash []byte) (*model.APIToken, error)

GetAPITokenByHash returns the token matching the given hash.

Looking a token up by its hash is what makes the stored value useless to anybody who reads the database: it cannot be turned back into a usable credential.

func GetConditionConfigs added in v0.10.0

func GetConditionConfigs(ctx context.Context, kind, id, config string, limit, page int) ([]model.ConfigCondition, int, error)

GetConditionConfigs returns a list of resource configurations from the database.

func GetConfigKind added in v0.10.0

func GetConfigKind(ctx context.Context, resourceType string) ([]string, error)

GetConfigKind returns a list of resource configurations from the database filtered by kind.

func GetLabelKeyOnlyRecords added in v0.14.0

func GetLabelKeyOnlyRecords(ctx context.Context, startTime, endTime string, limit, page int) ([]string, int, error)

GetLabelKeyOnlyRecords returns a list of labels from the labels database table.

func GetLabelRecords added in v0.14.0

func GetLabelRecords(ctx context.Context, id, key, value, startTime, endTime string, limit, page int) ([]model.Label, int, error)

GetLabelRecords returns a list of labels from the labels database table.

func GetSCM added in v0.10.0

func GetSCM(ctx context.Context, params GetSCMParams) ([]model.SCM, int, error)

GetSCM returns a list of scms from the scm database table.

func GetSourceConfigs added in v0.10.0

func GetSourceConfigs(ctx context.Context, kind, id, config string, limit, page int) ([]model.ConfigSource, int, error)

GetSourceConfigs returns a list of resource configurations from the database.

func GetTargetConfigs added in v0.10.0

func GetTargetConfigs(ctx context.Context, kind, id, config string, limit, page int) ([]model.ConfigTarget, int, error)

GetTargetConfigs returns a list of resource configurations from the database.

func InitLabels added in v0.14.0

func InitLabels(ctx context.Context, labels map[string]string) ([]uuid.UUID, error)

InitLabels takes a map of labels and ensures that they exist in the database, creating them if necessary.

func InsertAPIToken added in v0.17.1

func InsertAPIToken(ctx context.Context, name, subject, permission string, scopes []string, tokenHash []byte, expiresAt *time.Time) (*model.APIToken, error)

InsertAPIToken stores a new token and returns it.

Only the hash is passed in: the token itself is shown once, to whoever created it, and is never written down.

func InsertConfigResource added in v0.10.0

func InsertConfigResource(ctx context.Context, resourceType, resourceKind string, resourceConfig interface{}) (string, error)

InsertConfigResource inserts a new resource configuration into the database.

func InsertLabel added in v0.14.0

func InsertLabel(ctx context.Context, key, value string) (string, error)

InsertLabel creates a new label and inserts it into the database.

It returns the ID of the newly created label.

func InsertReport added in v0.10.0

func InsertReport(ctx context.Context, report reports.Report, publisher Publisher) (string, error)

func InsertSCM added in v0.10.0

func InsertSCM(ctx context.Context, url, branch string) (string, error)

InsertSCM creates a new SCM and inserts it into the database. It returns the ID of the newly created SCM.

func ListAPITokens added in v0.17.1

func ListAPITokens(ctx context.Context, subject string) ([]model.APIToken, error)

ListAPITokens returns the tokens of a subject, or every token when subject is empty, which only an administrator may ask for.

func Ping added in v0.21.0

func Ping(ctx context.Context) error

Ping reports whether the database answers.

func RunMigrationUp

func RunMigrationUp(ctx context.Context) error

RunMigrationUp applies the pending migrations. It returns as soon as ctx is done, even when a migration statement is blocked on a lock, so a signal can stop the startup.

The migration is then abandoned rather than canceled: the driver ignores contexts, so the statement keeps running on the server until it completes, and the migration table is left dirty, as it would be if the process were killed.

func SearchLatestReportByPipelineID added in v0.10.0

func SearchLatestReportByPipelineID(ctx context.Context, id string) (*model.PipelineReport, error)

SearchLatestReportByPipelineID searches the latest report for a specific pipeline id.

func SearchNumberOfReportsByPipelineID added in v0.10.0

func SearchNumberOfReportsByPipelineID(ctx context.Context, id string) (int, error)

SearchNumberOfReportsByPipelineID searches the number of reports for a specific pipeline id.

func SearchReport added in v0.10.0

func SearchReport(ctx context.Context, id string) (*model.PipelineReport, error)

SearchReport searches a report by its database record id.

func TouchAPIToken added in v0.17.1

func TouchAPIToken(ctx context.Context, id uuid.UUID) error

TouchAPIToken records that a token was just used.

A failure here is not worth failing the request it belongs to: the timestamp is there to help somebody spot an unused or a leaked token, not to authorize.

func UnacknowledgeAction added in v0.20.0

func UnacknowledgeAction(ctx context.Context, url string) error

UnacknowledgeAction removes the acknowledgement of an action, if there is one.

Types

type GCParams added in v0.18.0

type GCParams struct {
	// MaxHistoryDays is how many days of reports are kept. It must be at least 1,
	// anything lower would delete every report.
	MaxHistoryDays int
	// BatchSize is the maximum number of rows deleted by a single statement.
	BatchSize int
	// DryRun counts what would be deleted, without deleting anything.
	DryRun bool
}

GCParams defines what a garbage collection deletes.

type GCResult added in v0.18.0

type GCResult struct {
	Reports          int64
	SCMs             int64
	Labels           int64
	ConfigSources    int64
	ConfigConditions int64
	ConfigTargets    int64
	ActionAcks       int64
}

GCResult counts, per table, the rows a garbage collection deleted or would delete.

func GarbageCollect added in v0.18.0

func GarbageCollect(ctx context.Context, params GCParams) (GCResult, error)

GarbageCollect deletes the reports older than the retention, then the scms, labels and resource configs no remaining report references, and the action acknowledgements that expired before the retention cutoff.

Only one garbage collection deletes at a time across every udash instance sharing the database, the others return ErrGCLocked. A dry run does not take the lock.

func (GCResult) String added in v0.18.0

func (r GCResult) String() string

type GetSCMParams added in v0.16.0

type GetSCMParams struct {
	// ID restricts the lookup to a specific scm.
	ID string
	// URL restricts the lookup to the scms of a repository.
	URL string
	// Branch restricts the lookup to the scms of a branch.
	Branch string
	// StartTime and EndTime restrict the lookup to the scms a report was published for
	// within that range. Both must be provided, an empty range does not filter anything
	// out.
	StartTime string
	EndTime   string
	// Limit is the maximum number of scms to return, a value lower than one returns
	// them all. Page is one based.
	Limit int
	Page  int
}

GetSCMParams contains the filters used to look up scms.

type GetSCMSummaryParams added in v0.14.0

type GetSCMSummaryParams struct {
	MonitoringDurationDays int
	StartTime              string
	EndTime                string
	Labels                 map[string]string
	// Results restricts the summary to the reports whose pipeline result is one of
	// them. An empty list does not filter anything out.
	Results []string
	// OpenAction restricts the summary to the pipelines which carry an open action, such as
	// a pull request still waiting to be merged, or to the ones which do not. A nil value
	// does not filter anything out.
	OpenAction   *bool
	TotalCount   int
	TotalActions int
	Ctx          context.Context
	ScmRows      []model.SCM
}

type OpenActionAcknowledgement added in v0.20.0

type OpenActionAcknowledgement struct {
	// Until is when the acknowledgement expires. It lifts earlier if the worst result changes.
	Until time.Time `json:"until"`
	// By is who acknowledged the action. It is empty when authentication is off.
	By string `json:"by"`
}

OpenActionAcknowledgement records who acknowledged an open action, and until when.

type OpenActionData added in v0.19.0

type OpenActionData struct {
	// URL is the link of the action, which identifies it.
	URL string `json:"url"`
	// Title is the title of the action, as reported by its most recent pipeline.
	Title string `json:"title"`
	// Repository is the url of the git repository of the first target of the action carrying
	// an scm, as reported by its most recent pipeline. It falls back to the first target of
	// that pipeline carrying one, and is empty when none does.
	Repository string `json:"repository"`
	// Branch is the target branch of that same scm, which the pull request is merged into.
	Branch string `json:"branch"`
	// UpdatedAt is the last update date of its most recent pipeline.
	UpdatedAt time.Time `json:"updated_at"`
	// Pipelines contains every pipeline feeding the action, most recent first.
	Pipelines []OpenActionPipeline `json:"pipelines"`
	// Acknowledgement is only set on acknowledged actions, which the search returns
	// when SearchOpenActionsParams.Acknowledged is true.
	Acknowledgement *OpenActionAcknowledgement `json:"acknowledgement,omitempty"`
}

OpenActionData is an action left open, such as a pull request still waiting to be merged, along with every pipeline feeding it.

func SearchOpenActions added in v0.19.0

func SearchOpenActions(params SearchOpenActionsParams) ([]OpenActionData, int, int, error)

SearchOpenActions returns the actions left open by the latest report of every pipeline, one entry per action URL.

Several pipelines may feed the same action: manifests sharing a pipelineid push to the same branch, so Updatecli groups their changes into a single pull request. A pipeline whose report ID changed between two runs also keeps its previous report as the latest one of a pipeline of its own. Grouping by URL lists each pull request once either way.

That previous report is not superseded by the reports of the new ID though, nothing links the two. So once the pull request is merged, it is still listed from the previous report until that report falls out of the searched time range. The reports search reads the latest reports the same way and shares this limit.

It returns one page of actions, the total number of actions matching the request, and the number of acknowledged actions.

type OpenActionPipeline added in v0.19.0

type OpenActionPipeline struct {
	// ID is the database record id of the latest report of the pipeline.
	ID string `json:"id"`
	// Name is the name of the pipeline.
	Name string `json:"name"`
	// Result is the result of the latest report of the pipeline.
	Result string `json:"result"`
	// UpdatedAt is the last update date of the latest report of the pipeline.
	UpdatedAt time.Time `json:"updated_at"`
}

OpenActionPipeline is a pipeline whose latest report carries an open action.

type Options

type Options struct {
	// URI defines the DB URI
	URI               string
	MigrationDisabled bool
	// ConnectTimeout defines how long to wait for the database at startup, 2m by default.
	ConnectTimeout time.Duration
}

type Publisher added in v0.17.1

type Publisher struct {
	// Subject is the identity provider subject which published the report.
	Subject *string
	// TokenID is the API token used, when one was.
	TokenID *uuid.UUID
}

InsertReport inserts a new report into the database. Publisher identifies who published a report.

Both fields are optional: an instance running without authentication has nobody to attribute a report to, and a report published from the browser has no token.

type ReportResultSummaryEntry added in v0.16.0

type ReportResultSummaryEntry struct {
	// Date is the start of the bucket, in UTC, formatted as RFC3339.
	Date string `json:"date"`
	// Results contains the number of reports per Updatecli result for that bucket.
	Results map[string]int `json:"results"`
	// OpenActions contains, for each Updatecli result, how many of the reports counted in
	// Results also carry an open action, such as a pull request still waiting to be merged.
	// It is a breakdown of Results, not an addition to it, so its counts are always lower
	// than or equal to the matching ones in Results.
	//
	// The interesting one is the count reported under the success result: those pipelines
	// ran fine and had nothing to change only because the change is already waiting in a
	// pull request.
	OpenActions map[string]int `json:"open_actions"`
	// Total is the number of reports for that bucket, all results combined.
	Total int `json:"total"`
}

ReportResultSummaryEntry contains the number of reports per result for a single time bucket.

func SearchReportsSummary added in v0.16.0

func SearchReportsSummary(params ReportSummaryParams) ([]ReportResultSummaryEntry, int, error)

SearchReportsSummary returns the number of reports per result for each time bucket of the requested time range. Buckets without any report are reported with a zeroed entry so that the returned dataset always covers the whole time range.

The summary always covers whole buckets: an explicit time range is widened to the buckets it overlaps, otherwise a partial bucket would be reported as a drop of activity.

type ReportSearchOptions added in v0.10.0

type ReportSearchOptions struct {
	// Days is the how far to look back for reports from today.
	Days int
}

ReportSearchOptions contains options for searching reports.

type ReportSummaryParams added in v0.16.0

type ReportSummaryParams struct {
	Ctx context.Context
	// Days is how far back to look for reports, in days.
	// It is ignored when Hours, or StartTime and EndTime, are provided.
	Days int
	// Hours is how far back to look for reports, in hours. It takes precedence over
	// Days and is ignored when StartTime and EndTime are provided.
	Hours int
	// Granularity is the size of the time buckets, it defaults to a day.
	Granularity SummaryGranularity
	// MaxDays is the widest time range accepted, in days. A value lower than one
	// does not enforce any limit.
	MaxDays int
	// MaxBuckets is the largest number of buckets a summary may return. A value lower
	// than one does not enforce any limit.
	MaxBuckets int
	// StartTime and EndTime define an explicit time range, both must be provided.
	StartTime string
	EndTime   string
	// ScmID restricts the summary to the reports of a specific scm.
	ScmID string
	// Labels restricts the summary to the reports matching those labels.
	Labels map[string]string
	// Results restricts the summary to the reports whose pipeline result is one of
	// them. An empty list does not filter anything out.
	Results []string
	// OpenAction restricts the summary to the reports which carry an open action, such as
	// a pull request still waiting to be merged, or to the ones which do not. A nil value
	// does not filter anything out.
	OpenAction *bool
}

ReportSummaryParams contains the parameters used to summarize reports per time bucket.

type SCMBranchDataset added in v0.10.0

type SCMBranchDataset map[string]ScmSummaryData

SCMBranchDataset represents a map of branches and their summary data for a single SCM URL.

type SCMDataset added in v0.10.0

type SCMDataset struct {
	Data map[string]SCMBranchDataset `json:"data"`
}

SCMDataset represents the response for the FindSCMSummary endpoint.

func GetSCMSummary added in v0.10.0

func GetSCMSummary(params GetSCMSummaryParams) (*SCMDataset, error)

GetSCMSummary returns a list of scms summary from the scm database table.

Every scm is summarized by a single query. A summary covers every scm reported within its range, so running the query, and the label lookup, once per scm made it slower with every repository.

type ScmSummaryData added in v0.10.0

type ScmSummaryData struct {
	// ID is the unique identifier of the SCM.
	ID string `json:"id"`
	// TotalResultByType is a map of result types and their counts.
	TotalResultByType map[string]int `json:"total_result_by_type"`
	// TotalResult is the total number of results for this SCM.
	TotalResult int `json:"total_result"`
	// TotalActionURLs is the total number of unique action URLs for this SCM.
	TotalActionURLs int `json:"total_action_urls"`
	// TotalOpenActionByResult is a map of result types to the number of pipelines in that
	// result which also carry an open action, such as a pull request still waiting to be
	// merged. It is a breakdown of TotalResultByType, so its counts are always lower than
	// or equal to the matching ones there.
	//
	// Unlike TotalActionURLs, which counts distinct action URLs, this counts pipelines: a
	// single pull request grouping the changes of several pipelines is counted once there
	// and once per pipeline here.
	TotalOpenActionByResult map[string]int `json:"total_open_action_by_result"`
}

ScmSummaryData represents the summary data for a single SCM.

type SearchLatestReportData added in v0.10.0

type SearchLatestReportData struct {
	// ID represents the unique identifier of the report.
	ID string
	// Name represents the name of the report.
	Name string
	// Result represents the result of the report.
	Result string
	// Report contains the report data.
	Report reports.Report
	// FilteredResourceID contains the resource config ID that was filtered
	// It allows to identify in the report which resource was used to filter the report.
	FilteredResourceID string
	// CreatedAt represents the creation date of the report.
	CreatedAt string
	// UpdatedAt represents the last update date of the report.
	UpdatedAt string
	// TargetConfigIDs contains the config target IDs associated with the report.
	TargetConfigIDs pgtype.Hstore
	// ConditionConfigIDs contains the config condition IDs associated with the report.
	ConditionConfigIDs pgtype.Hstore
	// SourceConfigIDs contains the config source IDs associated with the report.
	SourceConfigIDs pgtype.Hstore
}

SearchLatestReportData represents a report.

func SearchLatestReports added in v0.13.0

func SearchLatestReports(params SearchLatestReportsParams) ([]SearchLatestReportData, int, error)

SearchLatestReports searches the latest reports according some parameters.

The reports are filtered, deduplicated, counted and paginated from their columns alone, and only the page is joined back to read the payloads. Deduplicating on the payload instead read the payload of every report within the range, twice, while a page only returns a few of them.

type SearchLatestReportsParams added in v0.14.0

type SearchLatestReportsParams struct {
	Ctx         context.Context
	ScmID       string
	SourceID    string
	ConditionID string
	TargetID    string
	Options     ReportSearchOptions
	StartTime   string
	EndTime     string
	Limit       int
	Page        int
	Latest      bool
	Labels      map[string]string
	// Results restricts the search to the reports whose pipeline result is one of
	// them. An empty list does not filter anything out.
	Results []string
	// OpenAction restricts the search to the reports which carry an open action, such as
	// a pull request still waiting to be merged, or to the ones which do not. A nil value
	// does not filter anything out.
	OpenAction *bool
}

type SearchOpenActionsParams added in v0.19.0

type SearchOpenActionsParams struct {
	Ctx       context.Context
	Options   ReportSearchOptions
	StartTime string
	EndTime   string
	Labels    map[string]string
	// ScmID restricts the search to the pipelines targeting that scm. An empty value does
	// not filter anything out, "none" only keeps the pipelines targeting none.
	ScmID string
	// Results restricts the search to the actions fed by at least one pipeline whose
	// latest result is one of them. An empty list does not filter anything out.
	Results []string
	// Acknowledged returns only the acknowledged actions instead of only the others.
	Acknowledged bool
	Limit        int
	Page         int
}

SearchOpenActionsParams contains the filters used to search the actions left open.

type SummaryGranularity added in v0.16.0

type SummaryGranularity string

SummaryGranularity is the size of the time buckets a reports summary is grouped by.

const (
	// SummaryGranularityHour groups the reports per UTC hour.
	SummaryGranularityHour SummaryGranularity = "hour"
	// SummaryGranularityDay groups the reports per UTC day.
	SummaryGranularityDay SummaryGranularity = "day"
	// SummaryGranularityWeek groups the reports per ISO week, starting on monday.
	SummaryGranularityWeek SummaryGranularity = "week"
	// SummaryGranularityMonth groups the reports per calendar month.
	SummaryGranularityMonth SummaryGranularity = "month"
)

func (SummaryGranularity) IsValid added in v0.16.0

func (g SummaryGranularity) IsValid() bool

IsValid reports whether the granularity is one this package knows how to bucket.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL