go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/led/job/info.go (about)

     1  // Copyright 2020 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package job
    16  
    17  import (
    18  	bbpb "go.chromium.org/luci/buildbucket/proto"
    19  	swarmingpb "go.chromium.org/luci/swarming/proto/api_v2"
    20  )
    21  
    22  // Info represents the common low-level information for all job Definitions.
    23  //
    24  // Swarming and Buildbucket implement this interface.
    25  type Info interface {
    26  	// SwarmingHostname retrieves the Swarming hostname this Definition will use.
    27  	SwarmingHostname() string
    28  
    29  	// TaskName retrieves the human-readable Swarming task name from the
    30  	// Definition.
    31  	TaskName() string
    32  
    33  	// CurrentIsolated returns the current isolated contents for the
    34  	// Definition. If the CASReference has no hash value,
    35  	// this returns an empty isolated obj.
    36  	//
    37  	// Returns error if this is a Swarming job where the slices have differing
    38  	// isolateds.
    39  	CurrentIsolated() (*swarmingpb.CASReference, error)
    40  
    41  	// Dimensions returns a single map of all dimensions in the job Definition
    42  	// and what their latest expiration is.
    43  	//
    44  	// For dimensions which "don't expire", they will report an expiration time of
    45  	// the total task expiration.
    46  	Dimensions() (ExpiringDimensions, error)
    47  
    48  	// CIPDPkgs returns the mapping of all CIPD packages in the task, in the
    49  	// same format that Editor.CIPDPkgs takes.
    50  	//
    51  	// Returns an error if not all slices in the swarming task have the same set
    52  	// of packages.
    53  	CIPDPkgs() (CIPDPkgs, error)
    54  
    55  	// Env returns any environment variable overrides in the job.
    56  	Env() (map[string]string, error)
    57  
    58  	// PrefixPathEnv returns the list of $PATH prefixes
    59  	PrefixPathEnv() ([]string, error)
    60  
    61  	// Priority returns the job's current swarming priority value.
    62  	Priority() int32
    63  
    64  	// Tags returns the job's current swarming tags.
    65  	Tags() []string
    66  }
    67  
    68  // HighLevelInfo represents high-level information for Buildbucket job
    69  // Definitions.
    70  //
    71  // HighLevelInfo includes all capabilities of `Info` as well.
    72  type HighLevelInfo interface {
    73  	Info
    74  
    75  	// Returns true iff the job is marked as 'experimental'.
    76  	Experimental() bool
    77  
    78  	// Returns a sorted list of enabled experiments.
    79  	Experiments() []string
    80  
    81  	// Returns the input properties of this build as a map of top-level key to
    82  	// its JSON-encoded value.
    83  	Properties() (map[string]string, error)
    84  
    85  	// TaskPayloadSource returns the CIPD package and version of the user's task
    86  	// payload. If they are empty, then it means the source of the user task
    87  	// payload is within the UserPayload in the job.Definition.
    88  	TaskPayloadSource() (cipdPkg, cipdVers string)
    89  
    90  	// TaskPayloadPath returns the location of where bbagent/kitchen will locate
    91  	// the task payload data within the task.
    92  	TaskPayloadPath() (path string)
    93  
    94  	// TaskPayloadCmd returns the arguments used to run the task payload.
    95  	//
    96  	// args[0] is the path, relative to the payload path, of the executable to
    97  	// run.
    98  	//
    99  	// If this is empty, it defaults to []string{"luciexe"}.
   100  	//
   101  	// NOTE: Kitchen tasks ignore this value.
   102  	TaskPayloadCmd() (args []string)
   103  
   104  	// Returns the gerrit changes associated with this job.
   105  	GerritChanges() []*bbpb.GerritChange
   106  
   107  	// Returns the gitiles commit associated with this job.
   108  	GitilesCommit() *bbpb.GitilesCommit
   109  }
   110  
   111  // Info returns a generic accessor object which can return generic information
   112  // about the Definition.
   113  //
   114  // Returns nil if the Definition doesn't support Info().
   115  func (jd *Definition) Info() Info {
   116  	if bb := jd.GetBuildbucket(); bb != nil {
   117  		return bbInfo{bb}
   118  	} else if sw := jd.GetSwarming(); sw != nil {
   119  		return swInfo{sw}
   120  	}
   121  	return nil
   122  }
   123  
   124  // HighLevelInfo returns an accessor object which can returns high-level
   125  // information about the Definition.
   126  //
   127  // Only returns a functioning implementation for Buildbucket jobs, otherwise
   128  // returns nil.
   129  func (jd *Definition) HighLevelInfo() HighLevelInfo {
   130  	if bb := jd.GetBuildbucket(); bb != nil {
   131  		return bbInfo{bb}
   132  	}
   133  	return nil
   134  }
   135  
   136  // returns the corresponding cas instance from job's Swarming hostname.
   137  func (jd *Definition) CasInstance() (string, error) {
   138  	return ToCasInstance(jd.Info().SwarmingHostname())
   139  }