ccv3

Documentation

Overview

Package ccv3 represents a Cloud Controller V3 client.

These sets of packages are still under development/pre-pre-pre...alpha. Use at your own risk! Functionality and design may change without warning.

It is currently designed to support Cloud Controller API 3.0.0. However, it may include features and endpoints of later API versions.

For more information on the Cloud Controller API see https://apidocs.cloudfoundry.org/

Method Naming Conventions

The client takes a '<Action Name><Top Level Endpoint><Return Value>' approach to method names. If the <Top Level Endpoint> and <Return Value> are similar, they do not need to be repeated. If a GUID is required for the <Top Level Endpoint>, the pluralization is removed from said endpoint in the method name.

For Example:

Method Name: GetApplication
Endpoint: /v3/applications/:guid
Action Name: Get
Top Level Endpoint: applications
Return Value: Application

Method Name: GetServiceInstances
Endpoint: /v3/service_instances
Action Name: Get
Top Level Endpoint: service_instances
Return Value: []ServiceInstance

Method Name: GetSpaceServiceInstances
Endpoint: /v3/spaces/:guid/service_instances
Action Name: Get
Top Level Endpoint: spaces
Return Value: []ServiceInstance

Use the following table to determine which HTTP Command equates to which Action Name:

HTTP Command -> Action Name
POST -> New
GET -> Get
PUT -> Update
DELETE -> Delete

Method Locations

Methods exist in the same file as their return type, regardless of which endpoint they use.

Error Handling

All error handling that requires parsing the error_code/code returned back from the Cloud Controller should be placed in the errorWrapper. Everything else can be handled in the individual operations. All parsed cloud controller errors should exist in errors.go, all generic HTTP errors should exist in the cloudcontroller's errors.go. Errors related to the individaul operation should exist at the top of that operation's file.

Index

• type APIInfo
  • func (info APIInfo) CloudControllerAPIVersion() string
  • func (info APIInfo) UAA() string
• type APILink
• type Application
• type CCError
• type CCErrorResponse
• type Client
  • func NewClient(appName string, appVersion string) *Client
  • func (client *Client) GetApplicationTasks(appGUID string, query url.Values) ([]Task, Warnings, error)
  • func (client *Client) GetApplications(query url.Values) ([]Application, Warnings, error)
  • func (client *Client) Info() (APIInfo, ResourceLinks, Warnings, error)
  • func (client *Client) NewTask(appGUID string, command string, name string, memory uint64, disk uint64) (Task, Warnings, error)
  • func (client *Client) TargetCF(settings TargetSettings) (Warnings, error)
  • func (client *Client) UpdateTask(taskGUID string) (Task, Warnings, error)
  • func (client *Client) WrapConnection(wrapper ConnectionWrapper)
• type ConnectionWrapper
• type NewTaskBody
• type PaginatedResources
  • func NewPaginatedResources(exampleResource interface{}) PaginatedResources
  • func (pr PaginatedResources) NextPage() string
  • func (pr PaginatedResources) Resources() ([]interface{}, error)
• type ResourceLinks
  • func (resources ResourceLinks) UnmarshalJSON(data []byte) error
• type TargetSettings
• type Task
• type TaskWorkersUnavailableError
  • func (e TaskWorkersUnavailableError) Error() string
• type UnexpectedResponseError
  • func (e UnexpectedResponseError) Error() string
• type Warnings

Types

type APIInfo

type APIInfo struct {
	// Links is a list of top level Cloud Controller APIs.
	Links struct {
		// CCV3 is the link to the Cloud Controller V3 API
		CCV3 APILink `json:"cloud_controller_v3"`

		// UAA is the link to the UAA API
		UAA APILink `json:"uaa"`
	} `json:"links"`
}

APIInfo represents a GET response from the '/' endpoint of the cloud controller API.

func (APIInfo) CloudControllerAPIVersion

func (info APIInfo) CloudControllerAPIVersion() string

CloudControllerAPIVersion return the version for the CloudController.

func (APIInfo) UAA

func (info APIInfo) UAA() string

UAA return the HREF for the UAA.

type APILink

type APILink struct {
	// HREF is the fully qualified URL for the link.
	HREF string `json:"href"`

	// Meta contains additional metadata about the API.
	Meta struct {
		// Version of the API
		Version string `json:"version"`
	} `json:"meta"`
}

APILink represents a generic link from a response object.

type Application

type Application struct {
	Name string `json:"name"`
	GUID string `json:"guid"`
}

Application represents a Cloud Controller V3 Application.

type CCError

type CCError struct {
	Code   int    `json:"code"`
	Detail string `json:"detail"`
	Title  string `json:"title"`
}

CCError represents a cloud controller error.

type CCErrorResponse

type CCErrorResponse struct {
	Errors []CCError `json:"errors"`
}

CCErrorResponse represents a generic Cloud Controller V3 error response.

type Client

type Client struct {
	APIInfo
	// contains filtered or unexported fields
}

Client can be used to talk to a Cloud Controller's V3 Endpoints.

func NewClient

func NewClient(appName string, appVersion string) *Client

NewClient returns a new Client.

func (*Client) GetApplicationTasks

func (client *Client) GetApplicationTasks(appGUID string, query url.Values) ([]Task, Warnings, error)

GetApplicationTasks returns a list of tasks associated with the provided application GUID. Results can be filtered by providing URL queries.

func (*Client) GetApplications

func (client *Client) GetApplications(query url.Values) ([]Application, Warnings, error)

GetApplications lists applications with optional filters.

func (*Client) Info

func (client *Client) Info() (APIInfo, ResourceLinks, Warnings, error)

Info returns back endpoint and API information from /v3.

func (*Client) NewTask

func (client *Client) NewTask(appGUID string, command string, name string, memory uint64, disk uint64) (Task, Warnings, error)

NewTask runs a command in the Application environment associated with the provided Application GUID.

func (*Client) TargetCF

func (client *Client) TargetCF(settings TargetSettings) (Warnings, error)

TargetCF sets the client to use the Cloud Controller specified in the configuration. Any other configuration is also applied to the client.

func (*Client) UpdateTask

func (client *Client) UpdateTask(taskGUID string) (Task, Warnings, error)

UpdateTask cancels a task.

func (*Client) WrapConnection

func (client *Client) WrapConnection(wrapper ConnectionWrapper)

WrapConnection wraps the current Client connection in the wrapper.

type ConnectionWrapper

type ConnectionWrapper interface {
	cloudcontroller.Connection
	Wrap(innerconnection cloudcontroller.Connection) cloudcontroller.Connection
}

ConnectionWrapper can wrap a given connection allowing the wrapper to modify all requests going in and out of the given connection.

type NewTaskBody

type NewTaskBody struct {
	Command    string `json:"command"`
	Name       string `json:"name,omitempty"`
	MemoryInMB uint64 `json:"memory_in_mb,omitempty"`
	DiskInMB   uint64 `json:"disk_in_mb,omitempty"`
}

NewTaskBody represents the body of the request to create a Task.

type PaginatedResources

type PaginatedResources struct {
	Pagination struct {
		Next struct {
			HREF string `json:"href"`
		} `json:"next"`
	} `json:"pagination"`
	ResourcesBytes json.RawMessage `json:"resources"`
	// contains filtered or unexported fields
}

PaginatedResources represents a page of resources returned by the Cloud Controller.

func NewPaginatedResources

func NewPaginatedResources(exampleResource interface{}) PaginatedResources

NewPaginatedResources returns a new PaginatedResources struct with the given resource type.

func (PaginatedResources) NextPage

func (pr PaginatedResources) NextPage() string

NextPage returns the HREF of the next page of results.

func (PaginatedResources) Resources

func (pr PaginatedResources) Resources() ([]interface{}, error)

Resources unmarshals JSON representing a page of resources and returns a slice of the given resource type.

type ResourceLinks

type ResourceLinks map[string]APILink

ResourceLinks represents the information returned back from /v3.

func (ResourceLinks) UnmarshalJSON

func (resources ResourceLinks) UnmarshalJSON(data []byte) error

UnmarshalJSON helps unmarshal a Cloud Controller /v3 response.

type TargetSettings

type TargetSettings struct {
	// DialTimeout is the DNS timeout used to make all requests to the Cloud
	// Controller.
	DialTimeout time.Duration

	// SkipSSLValidation controls whether a client verifies the server's
	// certificate chain and host name. If SkipSSLValidation is true, TLS accepts
	// any certificate presented by the server and any host name in that
	// certificate for *all* client requests going forward.
	//
	// In this mode, TLS is susceptible to man-in-the-middle attacks. This should
	// be used only for testing.
	SkipSSLValidation bool

	// URL is a fully qualified URL to the Cloud Controller API.
	URL string
}

TargetSettings represents configuration for establishing a connection to the Cloud Controller server.

type Task

type Task struct {
	GUID       string `json:"guid"`
	SequenceID int    `json:"sequence_id"`
	Name       string `json:"name"`
	Command    string `json:"command"`
	State      string `json:"state"`
	CreatedAt  string `json:"created_at"`
	MemoryInMB uint64 `json:"memory_in_mb"`
	DiskInMB   uint64 `json:"disk_in_mb"`
}

Task represents a Cloud Controller V3 Task.

type TaskWorkersUnavailableError

type TaskWorkersUnavailableError struct {
	Message string
}

TaskWorkersUnavailableError represents the case when no Diego workers are available.

func (TaskWorkersUnavailableError) Error

func (e TaskWorkersUnavailableError) Error() string

type UnexpectedResponseError

type UnexpectedResponseError struct {
	CCErrorResponse

	ResponseCode int
	RequestIDs   []string
}

UnexpectedResponseError is returned when the client gets an error that has not been accounted for.

func (UnexpectedResponseError) Error

func (e UnexpectedResponseError) Error() string

type Warnings

type Warnings []string

Warnings are a collection of warnings that the Cloud Controller can return back from an API request.