github.com/zppinho/prow@v0.0.0-20240510014325-1738badeb017/pkg/spyglass/api/spyglass.go (about)

     1  /*
     2  Copyright 2020 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package api
    18  
    19  import (
    20  	"encoding/json"
    21  
    22  	"sigs.k8s.io/prow/pkg/config"
    23  )
    24  
    25  // Key types specify the way Spyglass will fetch artifact handles
    26  const (
    27  	GCSKeyType  = "gcs"
    28  	ProwKeyType = "prowjob"
    29  )
    30  
    31  // Lens defines the interface that lenses are required to implement in order to be used by Spyglass.
    32  type Lens interface {
    33  	// Header returns a a string that is injected into the rendered lens's <head>
    34  	Header(artifacts []Artifact, resourceRoot string, config json.RawMessage, spyglassConfig config.Spyglass) string
    35  	// Body returns a string that is initially injected into the rendered lens's <body>.
    36  	// The lens's front-end code may call back to Body again, passing in some data string of its choosing.
    37  	Body(artifacts []Artifact, resourceRoot string, data string, config json.RawMessage, spyglassConfig config.Spyglass) string
    38  	// Callback receives a string sent by the lens's front-end code and returns another string to be returned
    39  	// to that frontend code.
    40  	Callback(artifacts []Artifact, resourceRoot string, data string, config json.RawMessage, spyglassConfig config.Spyglass) string
    41  }
    42  
    43  // Artifact represents some output of a prow job
    44  type Artifact interface {
    45  	// ReadAt reads len(p) bytes of the artifact at offset off. (unsupported on some compressed files)
    46  	ReadAt(p []byte, off int64) (n int, err error)
    47  	// ReadAtMost reads at most n bytes from the beginning of the artifact
    48  	ReadAtMost(n int64) ([]byte, error)
    49  	// CanonicalLink gets a link to viewing this artifact in storage
    50  	CanonicalLink() string
    51  	// JobPath is the path to the artifact within the job (i.e. without the job prefix)
    52  	JobPath() string
    53  	// ReadAll reads all bytes from the artifact up to a limit specified by the artifact
    54  	ReadAll() ([]byte, error)
    55  	// ReadTail reads the last n bytes from the artifact (unsupported on some compressed files)
    56  	ReadTail(n int64) ([]byte, error)
    57  	// Size gets the size of the artifact in bytes, may make a network call
    58  	Size() (int64, error)
    59  	// Metadata fetches the custom metadata associated with the artifact
    60  	Metadata() (map[string]string, error)
    61  	// UpdateMetadata modifies the custom metadata associated with the artifact
    62  	UpdateMetadata(map[string]string) error
    63  }
    64  
    65  // RequestAction defines the action for a request
    66  type RequestAction string
    67  
    68  const (
    69  	// RequestActionInitial means that this is the initial request for the given lense
    70  	RequestActionInitial RequestAction = "initial"
    71  	// RequestActionRerender means that this is a request to re-render the lenses body
    72  	RequestActionRerender RequestAction = "rerender"
    73  	// RequestActionCallBack means that this is an arbitrary callback
    74  	RequestActionCallBack RequestAction = "callback"
    75  )
    76  
    77  type LensRequest struct {
    78  	// Action is the specific type of request being made
    79  	Action RequestAction `json:"action"`
    80  	// Data is a string of data passed back from the lens frontend
    81  	Data string `json:"data,omitempty"`
    82  	// Config is the config for the lens, if any, in a lens-defined format
    83  	Config json.RawMessage `json:"config,omitempty"`
    84  	// ResourceRoot is a URL at which the lens's own resources can be accessed
    85  	// by the client browser.
    86  	ResourceRoot string `json:"resourceRoot"`
    87  	// Artifacts contains the artifacts for this request
    88  	Artifacts []string `json:"artifacts"`
    89  	// ArtifactSource is the source from which to fetch the artifacts
    90  	ArtifactSource string
    91  	// LensIndex is the index by which the lens config can be found
    92  	// TODO: Replace with something proper or avoid needing this
    93  	LensIndex int `json:"index"`
    94  }