package module
v11.0.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Apr 2, 2024 License: Apache-2.0 Imports: 11 Imported by: 8




A Go package for building V2 Open Service Broker API compliant Service Brokers.



  • Go
  • GNU Make 3.81


We appreciate and welcome open source contribution. We will try to review the changes as soon as we can.


brokerapi defines a ServiceBroker interface. Pass an implementation of this to brokerapi.New or brokerapi.NewWithOptions, which returns an http.Handler that you can use to serve handle HTTP requests.

Alternatively, if you already have a *chi.Mux that you want to attach service broker routes to, you can use brokerapi.AttachRoutes. Note in this case, the Basic Authentication and Originating Identity middleware will not be set up, so you will have to attach them manually if required.

Error types

brokerapi defines a handful of error types in service_broker.go for some common error cases that your service broker may encounter. Return these from your ServiceBroker methods where appropriate, and brokerapi will do the "right thing" (™), and give Cloud Foundry an appropriate status code, as per the Service Broker API specification.

Custom Errors

NewFailureResponse() allows you to return a custom error from any of the ServiceBroker interface methods which return an error. Within this you must define an error, a HTTP response status code and a logging key. You can also use the NewFailureResponseBuilder() to add a custom Error: value in the response, or indicate that the broker should return an empty response rather than the error message.

Request Context

When provisioning a service brokerapi validates the service_id and plan_id in the request, attaching the found instances to the request Context. These values can be retrieved in a brokerapi.ServiceBroker implementation using utility methods RetrieveServiceFromContext and RetrieveServicePlanFromContext as shown below.

func (sb *ServiceBrokerImplementation) Provision(ctx context.Context,
  instanceID string, details brokerapi.ProvisionDetails, asyncAllowed bool) {

  service := brokerapi.RetrieveServiceFromContext(ctx)
  if service == nil {
    // Lookup service

  // [..]

Originating Identity

The request context for every request contains the unparsed X-Broker-API-Originating-Identity header under the key originatingIdentity. More details on how the Open Service Broker API manages request originating identity is available here.

Request Identity

The request context for every request contains the unparsed X-Broker-API-Request-Identity header under the key requestIdentity. More details on how the Open Service Broker API manages request originating identity is available here.

Example Service Broker

You can see the cf-redis service broker uses the BrokerAPI package to create a service broker for Redis.


Releasing steps can be found here




View Source
const (
	PermissionRouteForwarding = domain.PermissionRouteForwarding
	PermissionSyslogDrain     = domain.PermissionSyslogDrain
	PermissionVolumeMount     = domain.PermissionVolumeMount

Deprecated: Use


View Source
var (
	ErrInstanceAlreadyExists = apiresponses.ErrInstanceAlreadyExists

	ErrInstanceDoesNotExist = apiresponses.ErrInstanceDoesNotExist

	ErrInstanceLimitMet = apiresponses.ErrInstanceLimitMet

	ErrBindingAlreadyExists = apiresponses.ErrBindingAlreadyExists

	ErrBindingDoesNotExist = apiresponses.ErrBindingDoesNotExist

	ErrBindingNotFound = apiresponses.ErrBindingNotFound

	ErrAsyncRequired = apiresponses.ErrAsyncRequired

	ErrPlanChangeNotSupported = apiresponses.ErrPlanChangeNotSupported

	ErrRawParamsInvalid = apiresponses.ErrRawParamsInvalid

	ErrAppGuidNotProvided = apiresponses.ErrAppGuidNotProvided

	ErrPlanQuotaExceeded = apiresponses.ErrPlanQuotaExceeded

	ErrServiceQuotaExceeded = apiresponses.ErrServiceQuotaExceeded

	ErrConcurrentInstanceAccess = apiresponses.ErrConcurrentInstanceAccess

	ErrMaintenanceInfoConflict = apiresponses.ErrMaintenanceInfoConflict

	ErrMaintenanceInfoNilConflict = apiresponses.ErrMaintenanceInfoNilConflict

Deprecated: Use


func AddServicePlanToContext

func AddServicePlanToContext(ctx context.Context, plan *ServicePlan) context.Context

func AddServiceToContext

func AddServiceToContext(ctx context.Context, service *Service) context.Context

func AttachRoutes

func AttachRoutes(router chi.Router, serviceBroker ServiceBroker, logger *slog.Logger)

func BindableValue deprecated

func BindableValue(v bool) *bool

Deprecated: Use

func FreeValue deprecated

func FreeValue(v bool) *bool

Deprecated: Use

func GetJsonNames deprecated

func GetJsonNames(s reflect.Value) (res []string)

Deprecated: Use

func New

func New(serviceBroker ServiceBroker, logger *slog.Logger, brokerCredentials BrokerCredentials) http.Handler

func NewFailureResponse deprecated

func NewFailureResponse(err error, statusCode int, loggerAction string) error

Deprecated: Use NewFailureResponse returns an error of type FailureResponse. err will by default be used as both a logging message and HTTP response description. statusCode is the HTTP status code to be returned, must be 4xx or 5xx loggerAction is a short description which will be used as the action if the error is logged.

func NewWithCustomAuth

func NewWithCustomAuth(serviceBroker ServiceBroker, logger *slog.Logger, authMiddleware middlewareFunc) http.Handler

func NewWithOptions

func NewWithOptions(serviceBroker domain.ServiceBroker, logger *slog.Logger, opts ...Option) http.Handler


type AsyncBindResponse deprecated

type AsyncBindResponse = apiresponses.AsyncBindResponse

Deprecated: Use

type BindDetails deprecated

type BindDetails = domain.BindDetails

Deprecated: Use

type BindResource deprecated

type BindResource = domain.BindResource

Deprecated: Use

type Binding deprecated

type Binding = domain.Binding

Deprecated: Use

type BindingResponse deprecated

type BindingResponse = apiresponses.BindingResponse

Deprecated: Use

type BrokerCredentials

type BrokerCredentials struct {
	Username string
	Password string

type CatalogResponse deprecated

type CatalogResponse = apiresponses.CatalogResponse

Deprecated: Use

type DeprovisionDetails deprecated

type DeprovisionDetails = domain.DeprovisionDetails

Deprecated: Use

type DeprovisionResponse deprecated

type DeprovisionResponse = apiresponses.DeprovisionResponse

Deprecated: Use

type DeprovisionServiceSpec deprecated

type DeprovisionServiceSpec = domain.DeprovisionServiceSpec

Deprecated: Use

type DetailsWithRawContext deprecated

type DetailsWithRawContext interface {

Deprecated: Use

type DetailsWithRawParameters deprecated

type DetailsWithRawParameters interface {

Deprecated: Use

type EmptyResponse deprecated

type EmptyResponse = apiresponses.EmptyResponse

Deprecated: Use

type ErrorResponse deprecated

type ErrorResponse = apiresponses.ErrorResponse

Deprecated: Use

type ExperimentalVolumeMount deprecated

type ExperimentalVolumeMount = domain.ExperimentalVolumeMount

Deprecated: Use

type ExperimentalVolumeMountBindingResponse deprecated

type ExperimentalVolumeMountBindingResponse = apiresponses.ExperimentalVolumeMountBindingResponse

Deprecated: Use

type ExperimentalVolumeMountPrivate deprecated

type ExperimentalVolumeMountPrivate = domain.ExperimentalVolumeMountPrivate

Deprecated: Use

type FailureResponse deprecated

type FailureResponse = apiresponses.FailureResponse

Deprecated: Use FailureResponse can be returned from any of the `ServiceBroker` interface methods which allow an error to be returned. Doing so will provide greater control over the HTTP response.

type FailureResponseBuilder deprecated

type FailureResponseBuilder = apiresponses.FailureResponseBuilder

Deprecated: Use FailureResponseBuilder provides a fluent set of methods to build a *FailureResponse.

func NewFailureResponseBuilder deprecated

func NewFailureResponseBuilder(err error, statusCode int, loggerAction string) *FailureResponseBuilder

Deprecated: Use NewFailureResponseBuilder returns a pointer to a newly instantiated FailureResponseBuilder Accepts required arguments to create a FailureResponse.

type GetBindingResponse deprecated

type GetBindingResponse = apiresponses.GetBindingResponse

Deprecated: Use

type GetBindingSpec deprecated

type GetBindingSpec = domain.GetBindingSpec

Deprecated: Use

type GetInstanceDetailsSpec deprecated

type GetInstanceDetailsSpec = domain.GetInstanceDetailsSpec

Deprecated: Use

type GetInstanceResponse deprecated

type GetInstanceResponse = apiresponses.GetInstanceResponse

Deprecated: Use

type LastOperation deprecated

type LastOperation = domain.LastOperation

Deprecated: Use

type LastOperationResponse deprecated

type LastOperationResponse = apiresponses.LastOperationResponse

Deprecated: Use

type LastOperationState deprecated

type LastOperationState = domain.LastOperationState

Deprecated: Use

const (
	InProgress LastOperationState = "in progress"
	Succeeded  LastOperationState = "succeeded"
	Failed     LastOperationState = "failed"

Deprecated: Use

type MaintenanceInfo deprecated

type MaintenanceInfo = domain.MaintenanceInfo

Deprecated: Use

type Option

type Option func(*config)

func WithAdditionalMiddleware

func WithAdditionalMiddleware(m middlewareFunc) Option

WithAdditionalMiddleware adds the specified middleware *after* the default middleware. Can be called multiple times. This option is ignored if `WithRouter()` is used.

func WithBrokerCredentials

func WithBrokerCredentials(brokerCredentials BrokerCredentials) Option

func WithCustomAuth

func WithCustomAuth(authMiddleware middlewareFunc) Option

WithCustomAuth adds the specified middleware *before* any other middleware. Despite the name, any middleware can be added whether nor not it has anything to do with authentication. But `WithAdditionalMiddleware()` may be a better choice if the middleware is not related to authentication. Can be called multiple times.

func WithEncodedPath deprecated

func WithEncodedPath() Option

WithEncodedPath used to opt in to a gorilla/mux behaviour that would treat encoded slashes "/" as IDs. For example, it would change `PUT /v2/service_instances/foo%2Fbar` to treat `foo%2Fbar` as an instance ID, while the default behavior was to treat it as `foo/bar`. However, with moving to go-chi/chi, this is now the default behavior so this option no longer does anything.

Deprecated: no longer has any effect

func WithOptions

func WithOptions(opts ...Option) Option

func WithRouter

func WithRouter(router chi.Router) Option

type PollDetails deprecated

type PollDetails = domain.PollDetails

Deprecated: Use

type PreviousValues deprecated

type PreviousValues = domain.PreviousValues

Deprecated: Use

type ProvisionDetails deprecated

type ProvisionDetails = domain.ProvisionDetails

Deprecated: Use

type ProvisionedServiceSpec deprecated

type ProvisionedServiceSpec = domain.ProvisionedServiceSpec

Deprecated: Use

type ProvisioningResponse deprecated

type ProvisioningResponse = apiresponses.ProvisioningResponse

Deprecated: Use

type RequiredPermission deprecated

type RequiredPermission = domain.RequiredPermission

Deprecated: Use

type Schema deprecated

type Schema = domain.Schema

Deprecated: Use

type Service deprecated

type Service = domain.Service

Deprecated: Use

func RetrieveServiceFromContext

func RetrieveServiceFromContext(ctx context.Context) *Service

type ServiceBindingSchema deprecated

type ServiceBindingSchema = domain.ServiceBindingSchema

Deprecated: Use

type ServiceBroker deprecated

type ServiceBroker interface {

Deprecated: Use Each method of the ServiceBroker interface maps to an individual endpoint of the Open Service Broker API.

The specification is available here:

The OpenAPI documentation is available here:

type ServiceDashboardClient deprecated

type ServiceDashboardClient = domain.ServiceDashboardClient

Deprecated: Use

type ServiceInstanceSchema deprecated

type ServiceInstanceSchema = domain.ServiceInstanceSchema

Deprecated: Use

type ServiceMetadata deprecated

type ServiceMetadata = domain.ServiceMetadata

Deprecated: Use

type ServicePlan deprecated

type ServicePlan = domain.ServicePlan

Deprecated: Use

func RetrieveServicePlanFromContext

func RetrieveServicePlanFromContext(ctx context.Context) *ServicePlan

type ServicePlanCost deprecated

type ServicePlanCost = domain.ServicePlanCost

Deprecated: Use

type ServicePlanMetadata deprecated

type ServicePlanMetadata = domain.ServicePlanMetadata

Deprecated: Use

type ServiceSchemas deprecated

type ServiceSchemas = domain.ServiceSchemas

Deprecated: Use

type SharedDevice deprecated

type SharedDevice = domain.SharedDevice

Deprecated: Use

type UnbindDetails deprecated

type UnbindDetails = domain.UnbindDetails

Deprecated: Use

type UnbindResponse deprecated

type UnbindResponse = apiresponses.UnbindResponse

Deprecated: Use

type UnbindSpec deprecated

type UnbindSpec = domain.UnbindSpec

Deprecated: Use

type UpdateDetails deprecated

type UpdateDetails = domain.UpdateDetails

Deprecated: Use

type UpdateResponse deprecated

type UpdateResponse = apiresponses.UpdateResponse

Deprecated: Use

type UpdateServiceSpec deprecated

type UpdateServiceSpec = domain.UpdateServiceSpec

Deprecated: Use

type VolumeMount deprecated

type VolumeMount = domain.VolumeMount

Deprecated: Use


Path Synopsis
Code generated by counterfeiter.
Code generated by counterfeiter.
Code generated by counterfeiter.
Code generated by counterfeiter.
Package blog is the brokerapi logger BrokerAPI was originally written to use the CloudFoundry Lager logger (, and it relied on some idiosyncrasies of that logger that are not found in the (subsequently written) Go standard library log/slog logger.
Package blog is the brokerapi logger BrokerAPI was originally written to use the CloudFoundry Lager logger (, and it relied on some idiosyncrasies of that logger that are not found in the (subsequently written) Go standard library log/slog logger.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL