github.com/dcarley/cf-cli@v6.24.1-0.20170220111324-4225ff346898+incompatible/api/cloudcontroller/ccv2/client.go (about)

     1  // Package ccv2 represents a Cloud Controller V2 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 2.23.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: /v2/applications/:guid
    23  //   Action Name: Get
    24  //   Top Level Endpoint: applications
    25  //   Return Value: Application
    26  //
    27  //   Method Name: GetServiceInstances
    28  //   Endpoint: /v2/service_instances
    29  //   Action Name: Get
    30  //   Top Level Endpoint: service_instances
    31  //   Return Value: []ServiceInstance
    32  //
    33  //   Method Name: GetSpaceServiceInstances
    34  //   Endpoint: /v2/spaces/:guid/service_instances
    35  //   Action Name: Get
    36  //   Top Level Endpoint: spaces
    37  //   Return Value: []ServiceInstance
    38  //
    39  // Use the following table to determine which HTTP Command equates to which
    40  // Action Name:
    41  //   HTTP Command -> Action Name
    42  //   POST -> New
    43  //   GET -> Get
    44  //   PUT -> Update
    45  //   DELETE -> Delete
    46  //
    47  // Method Locations
    48  //
    49  // Methods exist in the same file as their return type, regardless of which
    50  // endpoint they use.
    51  //
    52  // Error Handling
    53  //
    54  // All error handling that requires parsing the error_code/code returned back
    55  // from the Cloud Controller should be placed in the errorWrapper. Everything
    56  // else can be handled in the individual operations. All parsed cloud
    57  // controller errors should exist in errors.go, all generic HTTP errors should
    58  // exist in the cloudcontroller's errors.go. Errors related to the individaul
    59  // operation should exist at the top of that operation's file.
    60  //
    61  // No inline-relations-depth And summary Endpoints
    62  //
    63  // This package will not use ever use 'inline-relations-depth' or the
    64  // '/summary' endpoints for any operations. These requests can be extremely
    65  // taxing on the Cloud Controller and are avoided at all costs. Additionally,
    66  // the objects returned back from these requests can become extremely
    67  // inconsistant across versions and are problematic to deal with in general.
    68  package ccv2
    69  
    70  import (
    71  	"fmt"
    72  	"runtime"
    73  	"time"
    74  
    75  	"code.cloudfoundry.org/cli/api/cloudcontroller"
    76  	"github.com/tedsuo/rata"
    77  )
    78  
    79  // Warnings are a collection of warnings that the Cloud Controller can return
    80  // back from an API request.
    81  type Warnings []string
    82  
    83  // Client is a client that can be used to talk to a Cloud Controller's V2
    84  // Endpoints.
    85  type Client struct {
    86  	authorizationEndpoint     string
    87  	cloudControllerAPIVersion string
    88  	cloudControllerURL        string
    89  	dopplerEndpoint           string
    90  	minCLIVersion             string
    91  	routingEndpoint           string
    92  	tokenEndpoint             string
    93  
    94  	jobPollingInterval time.Duration
    95  	jobPollingTimeout  time.Duration
    96  
    97  	connection cloudcontroller.Connection
    98  	router     *rata.RequestGenerator
    99  	userAgent  string
   100  }
   101  
   102  // Config allows the Client to be configured
   103  type Config struct {
   104  	// AppName is the name of the application/process using the client.
   105  	AppName string
   106  
   107  	// AppVersion is the version of the application/process using the client.
   108  	AppVersion string
   109  
   110  	// JobPollingTimeout is the maximum amount of time a job polls for.
   111  	JobPollingTimeout time.Duration
   112  
   113  	// JobPollingInterval is the wait time between job polls.
   114  	JobPollingInterval time.Duration
   115  }
   116  
   117  // NewClient returns a new Cloud Controller Client.
   118  func NewClient(config Config) *Client {
   119  	userAgent := fmt.Sprintf("%s/%s (%s; %s %s)", config.AppName, config.AppVersion, runtime.Version(), runtime.GOARCH, runtime.GOOS)
   120  	return &Client{
   121  		userAgent:          userAgent,
   122  		jobPollingInterval: config.JobPollingInterval,
   123  		jobPollingTimeout:  config.JobPollingTimeout,
   124  	}
   125  }