protocol

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Mar 2, 2022 License: BSD-2-Clause Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RestLiProtocolVersion = "2.0.0"

	RestLiHeader_ID              = "X-RestLi-Id"
	RestLiHeader_Method          = "X-RestLi-Method"
	RestLiHeader_ProtocolVersion = "X-RestLi-Protocol-Version"
	RestLiHeader_ErrorResponse   = "X-RestLi-Error-Response"
)
View Source 
const (
	Method_Unknown = RestLiMethod(iota)

	Method_get
	Method_create
	Method_delete
	Method_update
	Method_partial_update

	Method_batch_get
	Method_batch_create
	Method_batch_delete
	Method_batch_update
	Method_batch_partial_update

	Method_get_all

	Method_action
	Method_finder
)

Disabled until https://github.com/golang/go/issues/45218 is resolved: go:generate stringer -type=RestLiMethod -trimprefix Method_

Variables

View Source 
var NilQueryParams = fmt.Errorf("go-restli: Query params cannot be nil")
View Source 
var RestLiMethodNameMapping = func() map[string]RestLiMethod {
	mapping := make(map[string]RestLiMethod)
	for m := Method_get; m <= Method_finder; m++ {
		mapping[m.String()] = m
	}
	return mapping
}()
View Source 
var StandardLogger stdLogger

StandardLogger represents the standard Logger from the log package (log.std for those inclined to read the source code)

Functions

func BatchCreateRequest added in v1.0.0 

func BatchCreateRequest[T restlicodec.Marshaler](
	ctx context.Context,
	url *url.URL,
	create []T,
	readOnlyFields restlicodec.PathSpec,
) (*http.Request, error)

func BoolPointer added in v0.26.7 

func BoolPointer(v bool) *bool

BoolPointer returns a pointer to the given parameter, useful for inlining setting optional fields

func BytesPointer added in v0.26.7 

func BytesPointer(v []byte) *[]byte

BytesPointer returns a pointer to the given parameter, useful for inlining setting optional fields

func CreateRequest added in v1.0.0 

func CreateRequest(
	ctx context.Context,
	url *url.URL,
	method RestLiMethod,
	create restlicodec.Marshaler,
	readOnlyFields restlicodec.PathSpec,
) (*http.Request, error)

func DoActionRequest added in v1.0.0 

func DoActionRequest(
	c *RestLiClient,
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	params restlicodec.Marshaler,
) (err error)

DoActionRequest executes a rest.li Action request and places the given restlicodec.Marshaler in the request's body and discards the response body. Actions with no params are expected to use the EmptyRecord.

func DoActionRequestWithResults added in v1.0.0 

func DoActionRequestWithResults[T any](
	c *RestLiClient,
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	params restlicodec.Marshaler,
	results restlicodec.GenericUnmarshaler[T],
) (t T, err error)

DoActionRequestWithResults executes a rest.li Action request and places the given restlicodec.Marshaler in the request's body, and returns the results after deserialization. Actions with no params are expected to use the EmptyRecord.

func DoAndUnmarshal added in v1.0.0 

func DoAndUnmarshal[V any](
	c *RestLiClient,
	req *http.Request,
	unmarshaler restlicodec.GenericUnmarshaler[V],
) (v V, res *http.Response, err error)

DoAndUnmarshal calls Do and attempts to unmarshal the response into the given value. The response body will always be read to EOF and closed, to ensure the connection can be reused.

func Float32Pointer added in v0.26.7 

func Float32Pointer(v float32) *float32

Float32Pointer returns a pointer to the given parameter, useful for inlining setting optional fields

func Float64Pointer added in v0.26.7 

func Float64Pointer(v float64) *float64

Float64Pointer returns a pointer to the given parameter, useful for inlining setting optional fields

func Int32Pointer added in v0.26.7 

func Int32Pointer(v int32) *int32

Int32Pointer returns a pointer to the given parameter, useful for inlining setting optional fields

func Int64Pointer added in v0.26.7 

func Int64Pointer(v int64) *int64

Int64Pointer returns a pointer to the given parameter, useful for inlining setting optional fields

func IntPointer added in v1.0.0 

func IntPointer(v int) *int

IntPointer returns a pointer to the given parameter, useful for inlining setting optional fields

func IsErrorResponse 

func IsErrorResponse(res *http.Response) error

IsErrorResponse checks the contents of the given http.Response and if the X-RestLi-Error-Response is set to `true`, parses the body of the response into a RestLiError. If the header is not set, but the status code isn't a 2xx code, an UnexpectedStatusCodeError will be returned instead. Note that an UnexpectedStatusCodeError contains the http.Request and http.Response that resulted in this error, therefore an expected non-2xx can always be manually handled/recovered (e.g. a 3xx code redirecting to the HTTPS endpoint).

func NewDeleteRequest added in v1.0.0 

func NewDeleteRequest(ctx context.Context, url *url.URL, method RestLiMethod) (*http.Request, error)

NewDeleteRequest creates a DELETE http.Request and sets the expected rest.li headers

func NewGetRequest added in v1.0.0 

func NewGetRequest(ctx context.Context, url *url.URL, method RestLiMethod) (*http.Request, error)

NewGetRequest creates a GET http.Request and sets the expected rest.li headers

func NewJsonRequest added in v1.0.0 

func NewJsonRequest(
	ctx context.Context,
	url *url.URL,
	httpMethod string,
	restLiMethod RestLiMethod,
	contents restlicodec.Marshaler,
	excludedFields restlicodec.PathSpec,
) (*http.Request, error)

NewJsonRequest creates an http.Request with the given HTTP method and rest.li method, and populates the body of the request with the given restlicodec.Marshaler contents (see RawJsonRequest)

func SetJsonAcceptHeader added in v0.7.0 

func SetJsonAcceptHeader(req *http.Request)

func SetJsonContentTypeHeader added in v0.3.0 

func SetJsonContentTypeHeader(req *http.Request)

func SetRestLiHeaders added in v0.2.0 

func SetRestLiHeaders(req *http.Request, method RestLiMethod)

func StringPointer added in v0.26.7 

func StringPointer(v string) *string

StringPointer returns a pointer to the given parameter, useful for inlining setting optional fields

Types

type ActionQueryParam added in v1.0.0 

type ActionQueryParam string

func (ActionQueryParam) EncodeQueryParams added in v1.0.0 

func (a ActionQueryParam) EncodeQueryParams() (string, error)

type BatchEntityUpdateResponse added in v0.26.6 

type BatchEntityUpdateResponse struct {
	Status int
}

func UnmarshalBatchEntityUpdateResponse added in v1.0.0 

func UnmarshalBatchEntityUpdateResponse(reader restlicodec.Reader) (r *BatchEntityUpdateResponse, err error)

func (*BatchEntityUpdateResponse) UnmarshalRestLi added in v0.26.6 

func (b *BatchEntityUpdateResponse) UnmarshalRestLi(reader restlicodec.Reader) error

type BatchQueryParams added in v1.0.0 

type BatchQueryParams[T any] interface {
	EncodeQueryParams(set batchkeyset.BatchKeySet[T]) (string, error)
}

type BatchRequestResponseError added in v1.0.0 

type BatchRequestResponseError[K comparable] map[K]*stdtypes.ErrorResponse

BatchRequestResponseError is returned by all the batch methods, and represents the keys on which the operation failed.

func (BatchRequestResponseError[K]) Error added in v1.0.0 

func (b BatchRequestResponseError[K]) Error() string

type CollectionClient added in v1.0.0 

type CollectionClient[K comparable, V, PartialV restlicodec.Marshaler] struct {
	SimpleClient[V, PartialV]
	KeyUnmarshaler      restlicodec.GenericUnmarshaler[K]
	BatchKeySetProvider func() batchkeyset.BatchKeySet[K]

	ReadOnlyFields   restlicodec.PathSpec
	CreateOnlyFields restlicodec.PathSpec
}

func (*CollectionClient[K, V, PV]) BatchCreate added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchCreate(
	ctx context.Context,
	rp ResourcePath,
	entities []V,
	query QueryParams,
) (createdEntities []*CreatedEntity[K], err error)

BatchCreate executes a batch_create with the given slice of entities

func (*CollectionClient[K, V, PV]) BatchCreateRequest added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchCreateRequest(
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	method RestLiMethod,
	create restlicodec.Marshaler,
) (*http.Request, error)

func (*CollectionClient[K, V, PV]) BatchCreateWithReturnEntity added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchCreateWithReturnEntity(
	ctx context.Context,
	rp ResourcePath,
	entities []V,
	query QueryParams,
) (createdEntities []*CreatedAndReturnedEntity[K, V], err error)

func (*CollectionClient[K, V, PV]) BatchDelete added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchDelete(
	ctx context.Context,
	rp ResourcePath,
	keys []K,
	query BatchQueryParams[K],
) (map[K]*BatchEntityUpdateResponse, error)

func (*CollectionClient[K, V, PV]) BatchGet added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchGet(
	ctx context.Context,
	rp ResourcePath,
	keys []K,
	query BatchQueryParams[K],
) (map[K]V, error)

func (*CollectionClient[K, V, PV]) BatchPartialUpdate added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchPartialUpdate(
	ctx context.Context,
	rp ResourcePath,
	entities map[K]PV,
	query BatchQueryParams[K],
) (map[K]*BatchEntityUpdateResponse, error)

func (*CollectionClient[K, V, PV]) BatchUpdate added in v1.0.0 

func (c *CollectionClient[K, V, PV]) BatchUpdate(
	ctx context.Context,
	rp ResourcePath,
	entities map[K]V,
	query BatchQueryParams[K],
) (map[K]*BatchEntityUpdateResponse, error)

func (*CollectionClient[K, V, PV]) Create added in v1.0.0 

func (c *CollectionClient[K, V, PV]) Create(
	ctx context.Context,
	rp ResourcePath,
	create V,
	query QueryParams,
) (*CreatedEntity[K], error)

Create executes a rest.li create request with the given object. The X-RestLi-Id header field will be parsed into id (though a CreateResponseHasNoEntityHeaderError will be returned if the header is not set). The response body will always be ignored.

func (*CollectionClient[K, V, PV]) CreateWithReturnEntity added in v1.0.0 

func (c *CollectionClient[K, V, PV]) CreateWithReturnEntity(
	ctx context.Context,
	rp ResourcePath,
	create V,
	query QueryParams,
) (*CreatedAndReturnedEntity[K, V], error)

CreateWithReturnEntity is like CollectionClient.Create, except it parses the returned entity from the response.

func (*CollectionClient[K, V, PV]) Find added in v1.0.0 

func (c *CollectionClient[K, V, PV]) Find(
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
) (*FinderResults[V], error)

Find executes a rest.li find request

func (*CollectionClient[K, V, PV]) NewCreateRequest added in v1.0.0 

func (c *CollectionClient[K, V, PV]) NewCreateRequest(
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	method RestLiMethod,
	create restlicodec.Marshaler,
) (*http.Request, error)

type CreateResponseHasNoEntityHeaderError added in v0.17.0 

type CreateResponseHasNoEntityHeaderError struct {
	Response *http.Response
}

CreateResponseHasNoEntityHeaderError is used specifically when a Create request succeeds but the resource implementation does not set the X-RestLi-Id header. This error is recoverable and can be ignored if the response id is not required

func (CreateResponseHasNoEntityHeaderError) Error added in v0.17.0 

func (c CreateResponseHasNoEntityHeaderError) Error() string

type CreatedAndReturnedEntity added in v1.0.0 

type CreatedAndReturnedEntity[K, V any] struct {
	CreatedEntity[K]
	Entity V
}

type CreatedEntity added in v1.0.0 

type CreatedEntity[K any] struct {
	Id     K
	Status int
}

type FinderResults added in v1.0.0 

type FinderResults[T any] struct {
	Results []T
	Total   *int
}

type FinderResultsWithMetadata added in v1.0.0 

type FinderResultsWithMetadata[T, M any] struct {
	FinderResults[T]
	Metadata M
}

func FindWithMetadata added in v1.0.0 

func FindWithMetadata[K comparable, V, PV restlicodec.Marshaler, M any](
	c *CollectionClient[K, V, PV],
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	metadataUnmarshaler restlicodec.GenericUnmarshaler[M],
) (results *FinderResultsWithMetadata[V, M], err error)

FindWithMetadata executes a rest.li find request for finders that declare metadata

type HostnameResolver added in v0.1.1 

type HostnameResolver interface {
	// ResolveHostnameAndContextForQuery takes in the name of the service for which to resolve the hostname, along with
	// the URL for the query that is about to be sent. The service name is often the top-level parent resource's name,
	// but can be any unique identifier for a D2 endpoint. Some HostnameResolver implementations will choose to ignore
	// this parameter and resolve hostnames using a different strategy. By default, the generated code will always pass
	// in the top-level parent resource's name.
	ResolveHostnameAndContextForQuery(serviceName string, query *url.URL) (*url.URL, error)
}

type IllegalPartialUpdateError added in v1.0.0 

type IllegalPartialUpdateError struct {
	Message    string
	RecordType string
	Field      string
}

IllegalPartialUpdateError is returned by PartialUpdateFieldChecker a partial update struct defines an illegal operation, such as deleting and setting the same field.

func (*IllegalPartialUpdateError) Error added in v1.0.0 

func (c *IllegalPartialUpdateError) Error() string

type LoggingRoundTripper added in v0.17.0 

type LoggingRoundTripper struct {
	http.RoundTripper
	Logger logger
}

LoggingRoundTripper is an http.RoundTripper that wraps a backing http.RoundTripper and logs all outbound queries (method, URL, headers and body) to the given logger

func (*LoggingRoundTripper) RoundTrip added in v0.17.0 

func (l *LoggingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

type PartialUpdateFieldChecker added in v1.0.0 

type PartialUpdateFieldChecker struct {
	RecordType string
	HasDeletes bool
	HasSets    bool
}

func (*PartialUpdateFieldChecker) CheckField added in v1.0.0 

func (c *PartialUpdateFieldChecker) CheckField(
	writer restlicodec.Writer,
	fieldName string,
	isDeleteSet bool,
	isSetSet bool,
	isPartialUpdateSet bool,
) error

type QueryParams added in v1.0.0 

type QueryParams interface {
	EncodeQueryParams() (string, error)
}

type QueryParamsString added in v1.0.0 

type QueryParamsString string

func (QueryParamsString) EncodeQueryParams added in v1.0.0 

func (q QueryParamsString) EncodeQueryParams() (string, error)

type ResourcePath added in v1.0.0 

type ResourcePath interface {
	RootResource() string
	ResourcePath() (path string, err error)
}

type ResourcePathString added in v1.0.0 

type ResourcePathString string

func (ResourcePathString) ResourcePath added in v1.0.0 

func (s ResourcePathString) ResourcePath() (string, error)

func (ResourcePathString) RootResource added in v1.0.0 

func (s ResourcePathString) RootResource() string

type RestLiClient 

type RestLiClient struct {
	*http.Client
	HostnameResolver
	// Whether or not missing fields in a restli response should cause a MissingRequiredFields error to be returned.
	// Note that even if the error is returned, the response will still be fully deserialized.
	StrictResponseDeserialization bool
}

func (*RestLiClient) Do 

func (c *RestLiClient) Do(req *http.Request) (*http.Response, error)

Do is a very thin shim between the standard http.Client.Do. All it does it parse the response into a RestLiError if the RestLi error header is set. A non-nil Response with a non-nil error will only occur if http.Client.Do returns such values (see the corresponding documentation). Otherwise, the response will only be non-nil if the error is nil. All (and only) network-related errors will be of type *url.Error. Other types of errors such as parse errors will use different error types.

func (*RestLiClient) DoAndIgnore added in v0.2.0 

func (c *RestLiClient) DoAndIgnore(req *http.Request) (*http.Response, error)

DoAndIgnore calls Do and drops the response's body. The response body will always be read to EOF and closed, to ensure the connection can be reused.

func (*RestLiClient) FormatQueryUrl 

func (c *RestLiClient) FormatQueryUrl(rp ResourcePath, query QueryParams) (*url.URL, error)

type RestLiError 

type RestLiError struct {
	stdtypes.ErrorResponse
	// Will be non-nil if an error occurred when attempting to deserialize the actual JSON response fields (i.e. Status,
	// Message, ExceptionClass and StackTrace)
	DeserializationError error `json:"-"`
	// The raw response that this error was parsed from. Note that to ensure that the connection can be reused, the Body
	// of the response is fully read into ResponseBody then closed
	Response     *http.Response `json:"-"`
	ResponseBody []byte         `json:"-"`
}

RestLiError is returned by the Do* methods when the X-RestLi-Error-Response header is set to true.

func (*RestLiError) Error 

func (r *RestLiError) Error() string

func (*RestLiError) Format added in v0.7.0 

func (r *RestLiError) Format(s fmt.State, verb rune)

type RestLiMethod added in v0.2.0 

type RestLiMethod int

func (RestLiMethod) String added in v0.7.0 

func (i RestLiMethod) String() string

type SimpleClient added in v1.0.0 

type SimpleClient[V, PV restlicodec.Marshaler] struct {
	*RestLiClient
	EntityUnmarshaler restlicodec.GenericUnmarshaler[V]

	CreateAndReadOnlyFields restlicodec.PathSpec
}

func (*SimpleClient[V, PV]) Delete added in v1.0.0 

func (c *SimpleClient[V, PV]) Delete(ctx context.Context, rp ResourcePath, query QueryParams) error

Delete executes a rest.li delete request

func (*SimpleClient[V, PV]) Get added in v1.0.0 

func (c *SimpleClient[V, PV]) Get(ctx context.Context, rp ResourcePath, query QueryParams) (v V, err error)

func (*SimpleClient[V, PV]) NewDeleteRequest added in v1.0.0 

func (c *SimpleClient[V, PV]) NewDeleteRequest(
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	method RestLiMethod,
) (*http.Request, error)

func (*SimpleClient[V, PV]) NewGetRequest added in v1.0.0 

func (c *SimpleClient[V, PV]) NewGetRequest(
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	method RestLiMethod,
) (*http.Request, error)

func (*SimpleClient[V, PV]) NewJsonRequest added in v1.0.0 

func (c *SimpleClient[V, PV]) NewJsonRequest(
	ctx context.Context,
	rp ResourcePath,
	query QueryParams,
	httpMethod string,
	restLiMethod RestLiMethod,
	contents restlicodec.Marshaler,
	excludedFields restlicodec.PathSpec,
) (*http.Request, error)

func (*SimpleClient[V, PV]) PartialUpdate added in v1.0.0 

func (c *SimpleClient[V, PV]) PartialUpdate(
	ctx context.Context,
	rp ResourcePath,
	patch PV,
	query QueryParams,
) error

PartialUpdate executes a rest.li partial update request with the given patch object

func (*SimpleClient[V, PV]) Update added in v1.0.0 

func (c *SimpleClient[V, PV]) Update(
	ctx context.Context,
	rp ResourcePath,
	update V,
	query QueryParams,
) error

Update executes a rest.li update request with the given update object

type SimpleHostnameResolver added in v0.17.0 

type SimpleHostnameResolver struct {
	Hostname *url.URL
}

func (*SimpleHostnameResolver) ResolveHostnameAndContextForQuery added in v0.17.0 

func (s *SimpleHostnameResolver) ResolveHostnameAndContextForQuery(string, *url.URL) (*url.URL, error)

type UnexpectedStatusCodeError added in v0.17.0 

type UnexpectedStatusCodeError struct {
	// The raw response that of the failed call. Note that to ensure that the connection can be reused, the Body
	// of the response is fully read into ResponseBody then closed
	Response     *http.Response
	ResponseBody []byte
}

UnexpectedStatusCodeError is returned by the Do* methods when the target rest.li service responded with non-2xx code but did not set the expected X-RestLi-Error-Response header.

func (*UnexpectedStatusCodeError) Error added in v0.17.0 

func (u *UnexpectedStatusCodeError) Error() string

type UnsupportedRestLiProtocolVersion added in v0.26.7 

type UnsupportedRestLiProtocolVersion struct {
	ReturnedVersion string
}

UnsupportedRestLiProtocolVersion is returned when the server returns a version other than the requested one, which is always RestLiProtocolVersion.

func (*UnsupportedRestLiProtocolVersion) Error added in v0.26.7 

func (u *UnsupportedRestLiProtocolVersion) Error() string

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.