github.com/drone/runner-go@v1.12.0/client/client.go (about)

     1  // Copyright 2019 Drone.IO Inc. All rights reserved.
     2  // Use of this source code is governed by the Polyform License
     3  // that can be found in the LICENSE file.
     4  
     5  // Package client provides a client for using the runner API.
     6  package client
     7  
     8  import (
     9  	"context"
    10  	"errors"
    11  
    12  	"github.com/drone/drone-go/drone"
    13  )
    14  
    15  // V1 is version 1 of the runner API
    16  const V1 = "application/vnd.drone.runner.v1+json"
    17  
    18  // ErrOptimisticLock is returned by if the struct being
    19  // modified has a Version field and the value is not equal
    20  // to the current value in the database
    21  var ErrOptimisticLock = errors.New("Optimistic Lock Error")
    22  
    23  type (
    24  	// Filter is used to filter the builds that are pulled
    25  	// from the queue.
    26  	Filter struct {
    27  		Kind    string            `json:"kind"`
    28  		Type    string            `json:"type"`
    29  		OS      string            `json:"os"`
    30  		Arch    string            `json:"arch"`
    31  		Variant string            `json:"variant"`
    32  		Kernel  string            `json:"kernel"`
    33  		Labels  map[string]string `json:"labels,omitempty"`
    34  	}
    35  
    36  	// File represents a file from the version control
    37  	// repository. It is used by the runner to provide the
    38  	// yaml configuration file to the runner.
    39  	File struct {
    40  		Data []byte
    41  		Hash []byte
    42  	}
    43  
    44  	// Context provides the runner with the build context and
    45  	// includes all environment data required to execute the
    46  	// build.
    47  	Context struct {
    48  		Build   *drone.Build    `json:"build"`
    49  		Stage   *drone.Stage    `json:"stage"`
    50  		Config  *File           `json:"config"`
    51  		Netrc   *drone.Netrc    `json:"netrc"`
    52  		Repo    *drone.Repo     `json:"repository"`
    53  		Secrets []*drone.Secret `json:"secrets"`
    54  		System  *drone.System   `json:"system"`
    55  	}
    56  )
    57  
    58  // A Client manages communication with the runner.
    59  type Client interface {
    60  	// Join notifies the server the runner is joining the cluster.
    61  	Join(ctx context.Context, machine string) error
    62  
    63  	// Leave notifies the server the runner is leaving the cluster.
    64  	Leave(ctx context.Context, machine string) error
    65  
    66  	// Ping sends a ping message to the server to test connectivity.
    67  	Ping(ctx context.Context, machine string) error
    68  
    69  	// Request requests the next available build stage for execution.
    70  	Request(ctx context.Context, args *Filter) (*drone.Stage, error)
    71  
    72  	// Accept accepts the build stage for execution.
    73  	Accept(ctx context.Context, stage *drone.Stage) error
    74  
    75  	// Detail gets the build stage details for execution.
    76  	Detail(ctx context.Context, stage *drone.Stage) (*Context, error)
    77  
    78  	// Update updates the build stage.
    79  	Update(ctxt context.Context, step *drone.Stage) error
    80  
    81  	// UpdateStep updates the build step.
    82  	UpdateStep(ctx context.Context, stage *drone.Step) error
    83  
    84  	// Watch watches for build cancellation requests.
    85  	Watch(ctx context.Context, stage int64) (bool, error)
    86  
    87  	// Batch batch writes logs to the build logs.
    88  	Batch(ctx context.Context, step int64, lines []*drone.Line) error
    89  
    90  	// Upload uploads the full logs to the server.
    91  	Upload(ctx context.Context, step int64, lines []*drone.Line) error
    92  
    93  	// UploadCard uploads a card to drone server.
    94  	UploadCard(ctx context.Context, step int64, card *drone.CardInput) error
    95  }