Documentation
¶
Index ¶
- Constants
- Variables
- func AcknowledgeAction(ctx context.Context, url string, until time.Time, worstResult, by string) error
- func Connect(ctx context.Context, o Options) error
- func DeleteAPIToken(ctx context.Context, id uuid.UUID, subject string) error
- func DeleteAPITokensBySubject(ctx context.Context, subject string) (int64, error)
- func DeleteConfigResource(ctx context.Context, resourceType string, id string) error
- func DeleteReport(ctx context.Context, id string) error
- func GetAPITokenByHash(ctx context.Context, tokenHash []byte) (*model.APIToken, error)
- func GetConditionConfigs(ctx context.Context, kind, id, config string, limit, page int) ([]model.ConfigCondition, int, error)
- func GetConfigKind(ctx context.Context, resourceType string) ([]string, error)
- func GetLabelKeyOnlyRecords(ctx context.Context, startTime, endTime string, limit, page int) ([]string, int, error)
- func GetLabelRecords(ctx context.Context, id, key, value, startTime, endTime string, ...) ([]model.Label, int, error)
- func GetSCM(ctx context.Context, params GetSCMParams) ([]model.SCM, int, error)
- func GetSourceConfigs(ctx context.Context, kind, id, config string, limit, page int) ([]model.ConfigSource, int, error)
- func GetTargetConfigs(ctx context.Context, kind, id, config string, limit, page int) ([]model.ConfigTarget, int, error)
- func InitLabels(ctx context.Context, labels map[string]string) ([]uuid.UUID, error)
- func InsertAPIToken(ctx context.Context, name, subject, permission string, scopes []string, ...) (*model.APIToken, error)
- func InsertConfigResource(ctx context.Context, resourceType, resourceKind string, ...) (string, error)
- func InsertLabel(ctx context.Context, key, value string) (string, error)
- func InsertReport(ctx context.Context, report reports.Report, publisher Publisher) (string, error)
- func InsertSCM(ctx context.Context, url, branch string) (string, error)
- func ListAPITokens(ctx context.Context, subject string) ([]model.APIToken, error)
- func Ping(ctx context.Context) error
- func RunMigrationUp(ctx context.Context) error
- func SearchLatestReportByPipelineID(ctx context.Context, id string) (*model.PipelineReport, error)
- func SearchNumberOfReportsByPipelineID(ctx context.Context, id string) (int, error)
- func SearchReport(ctx context.Context, id string) (*model.PipelineReport, error)
- func TouchAPIToken(ctx context.Context, id uuid.UUID) error
- func UnacknowledgeAction(ctx context.Context, url string) error
- type GCParams
- type GCResult
- type GetSCMParams
- type GetSCMSummaryParams
- type OpenActionAcknowledgement
- type OpenActionData
- type OpenActionPipeline
- type Options
- type Publisher
- type ReportResultSummaryEntry
- type ReportSearchOptions
- type ReportSummaryParams
- type SCMBranchDataset
- type SCMDataset
- type ScmSummaryData
- type SearchLatestReportData
- type SearchLatestReportsParams
- type SearchOpenActionsParams
- type SummaryGranularity
Constants ¶
const ResultUnknown = "?"
ResultUnknown replaces any result Udash does not recognize.
const (
URIEnvVariableName string = "UDASH_DB_URI"
)
Variables ¶
var ( URI string = os.Getenv(URIEnvVariableName) DB *pgxpool.Pool )
var ActionResults = []string{result.FAILURE, result.ATTENTION, ResultUnknown, result.SKIPPED, result.SUCCESS}
ActionResults lists the results an action can be acknowledged with, worst first: failure, attention (changed), unknown, skipped, success.
var ErrAPITokenNotFound = errors.New("api token not found")
ErrAPITokenNotFound is returned when no token matches the request.
var ( // ErrGCLocked is returned when another garbage collection is already running. ErrGCLocked = errors.New("another garbage collection is already running") )
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.
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.
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 ¶
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
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
DeleteAPITokensBySubject removes every token of a subject, which is what offboarding an identity needs.
func DeleteConfigResource ¶ added in v0.10.0
DeleteConfigResource deletes a resource configuration from the database.
func DeleteReport ¶ added in v0.10.0
DeleteReport deletes a report from the database.
func GetAPITokenByHash ¶ added in v0.17.1
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
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 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
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
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 InsertSCM ¶ added in v0.10.0
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
ListAPITokens returns the tokens of a subject, or every token when subject is empty, which only an administrator may ask for.
func RunMigrationUp ¶
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
SearchLatestReportByPipelineID searches the latest report for a specific pipeline id.
func SearchNumberOfReportsByPipelineID ¶ added in v0.10.0
SearchNumberOfReportsByPipelineID searches the number of reports for a specific pipeline id.
func SearchReport ¶ added in v0.10.0
SearchReport searches a report by its database record id.
func TouchAPIToken ¶ added in v0.17.1
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.
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
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.
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 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.