Documentation
¶
Overview ¶
Package artifact models links to files created during task execution.
Index ¶
- Constants
- Variables
- func ByTaskId(id string) db.Q
- func ByTaskIdAndExecution(id string, execution int) db.Q
- func ByTaskIds(taskIds []string) db.Q
- func ByTaskIdsAndExecutions(tasks []TaskIDAndExecution) db.Q
- func CanonicalizeStreamingContentType(contentType string, allowlist []string) (string, bool)
- func GenerateSignToken(appSecret []byte, taskID string, execution int, fileName string, ...) (token string, expiry int64)
- func PresignFile(ctx context.Context, file File, resolver CredentialResolver) (string, error)
- func UpdateFileKey(ctx context.Context, taskID string, execution int, ...) error
- func UpdateFileLink(ctx context.Context, taskID string, execution int, ...) error
- func ValidateFiles(files []File) error
- func ValidatePresignDuration(duration time.Duration) error
- func ValidateSignToken(appSecret []byte, taskID string, execution int, fileName string, token string, ...) bool
- type AssociatedLink
- type CredentialResolver
- type Credentials
- type Entry
- type File
- func EscapeFiles(files []File) []File
- func GetAllArtifacts(ctx context.Context, tasks []TaskIDAndExecution) ([]File, error)
- func RemoveInvalidLinks(files []File) ([]File, error)
- func StripHiddenFiles(ctx context.Context, files []File, hasUser bool, resolver CredentialResolver) ([]File, error)
- func StripHiddenFilesLazy(files []File, hasUser bool, baseURL string, taskID string, execution int, ...) []File
- type Params
- type TaskIDAndExecution
Constants ¶
const ( // strings for setting visibility Public = "public" Private = "private" None = "none" Signed = "signed" )
const Collection = "artifact_files"
Variables ¶
var ( // BSON fields for artifact file structs TaskIdKey = bsonutil.MustHaveTag(Entry{}, "TaskId") TaskNameKey = bsonutil.MustHaveTag(Entry{}, "TaskDisplayName") BuildIdKey = bsonutil.MustHaveTag(Entry{}, "BuildId") FilesKey = bsonutil.MustHaveTag(Entry{}, "Files") ExecutionKey = bsonutil.MustHaveTag(Entry{}, "Execution") CreateTimeKey = bsonutil.MustHaveTag(Entry{}, "CreateTime") NameKey = bsonutil.MustHaveTag(File{}, "Name") LinkKey = bsonutil.MustHaveTag(File{}, "Link") ContentTypeKey = bsonutil.MustHaveTag(File{}, "ContentType") AWSSecretKey = bsonutil.MustHaveTag(File{}, "AWSSecret") FileKeyKey = bsonutil.MustHaveTag(File{}, "FileKey") )
Functions ¶
func ByTaskIdAndExecution ¶
ByTaskIdAndExecution returns a query for entries with the given Task Id and execution number
func ByTaskIdsAndExecutions ¶
func ByTaskIdsAndExecutions(tasks []TaskIDAndExecution) db.Q
func CanonicalizeStreamingContentType ¶
CanonicalizeStreamingContentType returns the canonical header value to serve if the task-supplied content type exactly matches an allowlist entry, including its parameters, and false otherwise. Parsing (not prefix-matching) rejects ambiguous values like "text/plain,text/html". Callers must serve the returned value, not the stored string.
func GenerateSignToken ¶
func GenerateSignToken(appSecret []byte, taskID string, execution int, fileName string, validFor time.Duration) (token string, expiry int64)
GenerateSignToken creates a token and expiry for an artifact sign URL. The token expires after validFor.
func PresignFile ¶
PresignFile generates a presigned S3 URL for the given artifact file.
func UpdateFileKey ¶
func UpdateFileKey(ctx context.Context, taskID string, execution int, fileName, currentFileKey, newFileKey string) error
UpdateFileKey updates the S3 file key for a single artifact file matching task ID, execution, file name, and current file key. This is used for rotating S3 signed artifacts to point to a different object in the same bucket.
func UpdateFileLink ¶
func UpdateFileLink(ctx context.Context, taskID string, execution int, fileName, currentLink, newLink string) error
UpdateFileLink updates the link for a single artifact file matching task ID, execution, file name, and current link. Returns db.ErrNotFound if no file matched.
func ValidateFiles ¶
ValidateFiles checks that artifact and associated links are absolute HTTP(S) or T2 URLs. DoNotEncodeLink affects escaping but does not bypass validation.
func ValidatePresignDuration ¶
ValidatePresignDuration checks that a configured duration is supported by S3.
Types ¶
type AssociatedLink ¶
type AssociatedLink struct {
Name string `json:"name" bson:"name"`
Link string `json:"link" bson:"link"`
DoNotEncodeLink bool `json:"do_not_encode_link,omitempty" bson:"do_not_encode_link,omitempty"`
}
AssociatedLink represents a link related to a file besides the main artifact link.
type CredentialResolver ¶
type CredentialResolver func(ctx context.Context, file File) (*Credentials, error)
CredentialResolver resolves the static credentials to presign a file with from the owning project's current configuration. A nil result or an error means the credentials stored on the artifact should be used. Resolvers cache per task, so they must not be shared across requests. Use model.NewArtifactCredentialResolver to construct one.
type Credentials ¶
Credentials are the static AWS credentials used to presign an artifact URL. A file uploaded with a role ARN needs none, since STS mints credentials per presign.
type Entry ¶
type Entry struct {
TaskId string `json:"task" bson:"task"`
TaskDisplayName string `json:"task_name" bson:"task_name"`
BuildId string `json:"build" bson:"build"`
Files []File `json:"files" bson:"files"`
Execution int `json:"execution" bson:"execution"`
CreateTime time.Time `json:"create_time" bson:"create_time"`
}
Entry stores groups of names and links (not content!) for files uploaded to the api server by a running agent. These links could be for build or task-relevant files (things like extra results, test coverage, etc.)
type File ¶
type File struct {
// Name is a human-readable name for the file being linked, e.g. "Coverage Report"
Name string `json:"name" bson:"name"`
// Link is the link to the file, e.g. "http://fileserver/coverage.html"
Link string `json:"link" bson:"link"`
// Visibility determines who can see the file in the UI
Visibility string `json:"visibility" bson:"visibility"`
// When true, these artifacts are excluded from reproduction
IgnoreForFetch bool `bson:"fetch_ignore,omitempty" json:"ignore_for_fetch"`
// AWSKey is the key with which the file was uploaded to S3.
AWSKey string `json:"aws_key,omitempty" bson:"aws_key,omitempty"`
// AWSSecret is the secret with which the file was uploaded to S3.
AWSSecret string `json:"aws_secret,omitempty" bson:"aws_secret,omitempty"`
// AWSRoleARN is the role ARN with which the file was uploaded to S3.
AWSRoleARN string `json:"aws_role_arn,omitempty" bson:"aws_role_arn,omitempty"`
// AWSKeyVarName is the name of the project variable that supplied AWSKey.
AWSKeyVarName string `json:"aws_key_var_name,omitempty" bson:"aws_key_var_name,omitempty"`
// AWSSecretVarName is the name of the project variable that supplied AWSSecret.
AWSSecretVarName string `json:"aws_secret_var_name,omitempty" bson:"aws_secret_var_name,omitempty"`
// AWSAccountID is the resolved account ID for key+secret uploads (empty when AWSRoleARN is set).
AWSAccountID string `json:"aws_account_id,omitempty" bson:"aws_account_id,omitempty"`
// ExternalID is the external ID with which the file was uploaded to S3.
ExternalID string `json:"external_id,omitempty" bson:"external_id,omitempty"`
// Bucket is the aws bucket in which the file is stored.
Bucket string `json:"bucket,omitempty" bson:"bucket,omitempty"`
// FileKey is the path to the file in the bucket.
FileKey string `json:"filekey,omitempty" bson:"filekey,omitempty"`
// ContentType is the content type of the file.
ContentType string `json:"content_type" bson:"content_type"`
// FileSize is the size of the file in bytes.
FileSize int64 `json:"file_size,omitempty" bson:"file_size,omitempty"`
// PutRequests is the number of S3 PUT requests made to upload this file.
PutRequests int `json:"put_requests,omitempty" bson:"put_requests,omitempty"`
// PutCost is the calculated S3 PUT request cost for uploading this file.
PutCost float64 `json:"put_cost,omitempty" bson:"put_cost,omitempty"`
// AssociatedLinks is a list of links related to the file besides the main artifact link.
AssociatedLinks []AssociatedLink `json:"associated_links,omitempty" bson:"associated_links,omitempty"`
// DoNotEncodeLink indicates that the file link should not be escaped.
DoNotEncodeLink bool `json:"do_not_encode_link,omitempty" bson:"do_not_encode_link,omitempty"`
// PresignDuration is how long a presigned URL for this file remains valid.
PresignDuration time.Duration `json:"presign_duration,omitempty" bson:"presign_duration,omitempty"`
}
File is a pairing of name and link for easy storage/display
func EscapeFiles ¶
EscapeFiles escapes the base of the file link to avoid issues opening links with special characters in the UI. Note that it will not escape path segments other than the base (i.e. the last one). Note: Links will not be escaped if the file or associated link's DoNotEncode field is set to true, or if the link already appears to be escaped. For example, "url.com/something+another/file#1.tar.gz" will be escaped to "url.com/something+another/file%231.tar.gz".
func GetAllArtifacts ¶
func GetAllArtifacts(ctx context.Context, tasks []TaskIDAndExecution) ([]File, error)
func RemoveInvalidLinks ¶
RemoveInvalidLinks returns the files with any links that fail ValidateFiles removed. An artifact with an invalid link is removed entirely, whereas an invalid associated link only removes that associated link from its artifact. The returned error describes everything that was removed and is nil if all links are valid.
func StripHiddenFiles ¶
func StripHiddenFiles(ctx context.Context, files []File, hasUser bool, resolver CredentialResolver) ([]File, error)
StripHiddenFiles is a helper for only showing users the files they are allowed to see. It also pre-signs file URLs.
func StripHiddenFilesLazy ¶
func StripHiddenFilesLazy(files []File, hasUser bool, baseURL string, taskID string, execution int, appSecret []byte) []File
StripHiddenFilesLazy filters files by visibility and replaces signed file links with lazy redirect URLs that include a token, instead of eagerly presigning them.
type Params ¶
Params stores file entries as key-value pairs, for easy parameter parsing.
Key = Human-readable name for file Value = link for the file