github.com/loggregator/cli@v6.33.1-0.20180224010324-82334f081791+incompatible/api/cloudcontroller/ccv3/client.go (about)

     1  // Package ccv3 represents a Cloud Controller V3 client.
     2  //
     3  // These sets of packages are still under development/pre-pre-pre...alpha. Use
     4  // at your own risk! Functionality and design may change without warning.
     5  //
     6  // It is currently designed to support Cloud Controller API 3.0.0. However, it
     7  // may include features and endpoints of later API versions.
     8  //
     9  // For more information on the Cloud Controller API see
    10  // https://apidocs.cloudfoundry.org/
    11  //
    12  // Method Naming Conventions
    13  //
    14  // The client takes a '<Action Name><Top Level Endpoint><Return Value>'
    15  // approach to method names.  If the <Top Level Endpoint> and <Return Value>
    16  // are similar, they do not need to be repeated. If a GUID is required for the
    17  // <Top Level Endpoint>, the pluralization is removed from said endpoint in the
    18  // method name.
    19  //
    20  // For Example:
    21  //   Method Name: GetApplication
    22  //   Endpoint: /v3/applications/:guid
    23  //   Action Name: Get
    24  //   Top Level Endpoint: applications
    25  //   Return Value: Application
    26  //
    27  //   Method Name: GetServiceInstances
    28  //   Endpoint: /v3/service_instances
    29  //   Action Name: Get
    30  //   Top Level Endpoint: service_instances
    31  //   Return Value: []ServiceInstance
    32  //
    33  //   Method Name: GetSpaceServiceInstances
    34  //   Endpoint: /v3/spaces/:guid/service_instances
    35  //   Action Name: Get
    36  //   Top Level Endpoint: spaces
    37  //   Return Value: []ServiceInstance
    38  //
    39  //   Method Name: CreateApplicationTask
    40  //   Endpoint: /v3/apps/:application_guid/task
    41  //   Action Name: Post
    42  //   Top Level Endpoint: apps
    43  //   Return Value: []Task
    44  //
    45  // Use the following table to determine which HTTP Command equates to which
    46  // Action Name:
    47  //   HTTP Command -> Action Name
    48  //   POST -> Create
    49  //   GET -> Get
    50  //   PUT -> Update
    51  //   DELETE -> Delete
    52  //   PATCH -> Patch
    53  //
    54  // Method Locations
    55  //
    56  // Methods exist in the same file as their return type, regardless of which
    57  // endpoint they use.
    58  //
    59  // Error Handling
    60  //
    61  // All error handling that requires parsing the error_code/code returned back
    62  // from the Cloud Controller should be placed in the errorWrapper. Everything
    63  // else can be handled in the individual operations. All parsed cloud
    64  // controller errors should exist in errors.go, all generic HTTP errors should
    65  // exist in the cloudcontroller's errors.go. Errors related to the individaul
    66  // operation should exist at the top of that operation's file.
    67  package ccv3
    68  
    69  import (
    70  	"fmt"
    71  	"runtime"
    72  	"time"
    73  
    74  	"code.cloudfoundry.org/cli/api/cloudcontroller"
    75  	"code.cloudfoundry.org/cli/api/cloudcontroller/ccv3/internal"
    76  )
    77  
    78  // Warnings are a collection of warnings that the Cloud Controller can return
    79  // back from an API request.
    80  type Warnings []string
    81  
    82  // Client can be used to talk to a Cloud Controller's V3 Endpoints.
    83  type Client struct {
    84  	APIInfo
    85  	cloudControllerURL string
    86  
    87  	connection cloudcontroller.Connection
    88  	router     *internal.Router
    89  	userAgent  string
    90  	wrappers   []ConnectionWrapper
    91  
    92  	jobPollingInterval time.Duration
    93  	jobPollingTimeout  time.Duration
    94  }
    95  
    96  // Config allows the Client to be configured
    97  type Config struct {
    98  	// AppName is the name of the application/process using the client.
    99  	AppName string
   100  
   101  	// AppVersion is the version of the application/process using the client.
   102  	AppVersion string
   103  
   104  	// JobPollingTimeout is the maximum amount of time a job polls for.
   105  	JobPollingTimeout time.Duration
   106  
   107  	// JobPollingInterval is the wait time between job polls.
   108  	JobPollingInterval time.Duration
   109  
   110  	// Wrappers that apply to the client connection.
   111  	Wrappers []ConnectionWrapper
   112  }
   113  
   114  // NewClient returns a new Client.
   115  func NewClient(config Config) *Client {
   116  	userAgent := fmt.Sprintf("%s/%s (%s; %s %s)", config.AppName, config.AppVersion, runtime.Version(), runtime.GOARCH, runtime.GOOS)
   117  	return &Client{
   118  		userAgent:          userAgent,
   119  		jobPollingInterval: config.JobPollingInterval,
   120  		jobPollingTimeout:  config.JobPollingTimeout,
   121  		wrappers:           append([]ConnectionWrapper{newErrorWrapper()}, config.Wrappers...),
   122  	}
   123  }