github.com/ablease/cli@v6.37.1-0.20180613014814-3adbb7d7fb19+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  // Additionally, if the endpoint is an "action" endpoint, do not include the
    21  // word "Action" in the method name.
    22  //
    23  // For Example:
    24  //   Method Name: GetApplication
    25  //   Endpoint: /v3/applications/:guid
    26  //   Action Name: Get
    27  //   Top Level Endpoint: applications
    28  //   Return Value: Application
    29  //
    30  //   Method Name: GetServiceInstances
    31  //   Endpoint: /v3/service_instances
    32  //   Action Name: Get
    33  //   Top Level Endpoint: service_instances
    34  //   Return Value: []ServiceInstance
    35  //
    36  //   Method Name: GetSpaceServiceInstances
    37  //   Endpoint: /v3/spaces/:guid/service_instances
    38  //   Action Name: Get
    39  //   Top Level Endpoint: spaces
    40  //   Return Value: []ServiceInstance
    41  //
    42  //   Method Name: CreateApplicationTask
    43  //   Endpoint: /v3/apps/:application_guid/task
    44  //   Action Name: Post
    45  //   Top Level Endpoint: apps
    46  //   Return Value: Task
    47  //
    48  // Use the following table to determine which HTTP Command equates to which
    49  // Action Name:
    50  //   HTTP Command -> Action Name
    51  //   POST -> Create OR Update*
    52  //   GET -> Get
    53  //   PUT -> Update
    54  //   DELETE -> Delete
    55  //   PATCH -> Update
    56  //
    57  // * - In some cases POSTs are updating resources, in these cases the method
    58  // should be called Update, not Create.
    59  //
    60  // Method Locations
    61  //
    62  // Methods exist in the same file as their return type, regardless of which
    63  // endpoint they use.
    64  //
    65  // Error Handling
    66  //
    67  // All error handling that requires parsing the error_code/code returned back
    68  // from the Cloud Controller should be placed in the errorWrapper. Everything
    69  // else can be handled in the individual operations. All parsed cloud
    70  // controller errors should exist in errors.go, all generic HTTP errors should
    71  // exist in the cloudcontroller's errors.go. Errors related to the individual
    72  // operation should exist at the top of that operation's file.
    73  package ccv3
    74  
    75  import (
    76  	"fmt"
    77  	"runtime"
    78  	"time"
    79  
    80  	"code.cloudfoundry.org/cli/api/cloudcontroller"
    81  	"code.cloudfoundry.org/cli/api/cloudcontroller/ccv3/internal"
    82  )
    83  
    84  // Warnings are a collection of warnings that the Cloud Controller can return
    85  // back from an API request.
    86  type Warnings []string
    87  
    88  // Client can be used to talk to a Cloud Controller's V3 Endpoints.
    89  type Client struct {
    90  	Info
    91  	cloudControllerURL string
    92  
    93  	connection cloudcontroller.Connection
    94  	router     *internal.Router
    95  	userAgent  string
    96  	wrappers   []ConnectionWrapper
    97  
    98  	jobPollingInterval time.Duration
    99  	jobPollingTimeout  time.Duration
   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  	// Wrappers that apply to the client connection.
   117  	Wrappers []ConnectionWrapper
   118  }
   119  
   120  // NewClient returns a new Client.
   121  func NewClient(config Config) *Client {
   122  	userAgent := fmt.Sprintf("%s/%s (%s; %s %s)", config.AppName, config.AppVersion, runtime.Version(), runtime.GOARCH, runtime.GOOS)
   123  	return &Client{
   124  		userAgent:          userAgent,
   125  		jobPollingInterval: config.JobPollingInterval,
   126  		jobPollingTimeout:  config.JobPollingTimeout,
   127  		wrappers:           append([]ConnectionWrapper{newErrorWrapper()}, config.Wrappers...),
   128  	}
   129  }