stub

package module
v0.18.12 Latest Latest
Warning

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

 Go to latest Published: Dec 30, 2024 License: BSD-3-Clause Imports: 25 Imported by: 6

README

STUB

Go Reference Go Report Card

This package provides a set of utilities and helper methods to call a REST or RPC (over websocket) Many of the boilerplate codes are not necessary anymore when you use stub and it provides many handy features.

REST example:

package main

import (
	"context"
	"net/http"

	"github.com/clubpay/ronykit/stub"
)

func main() {
	ctx := context.Background()
	s := stub.New("webhook.site", stub.Secure())
	httpCtx := s.REST().
		SetMethod(http.MethodGet).
		SetHeader("Content-Type", "application/json").
		SetPath("/22fda9e7-1660-406e-b11e-993e070f175e").
		SetQuery("someKey", "someValue").
		Run(ctx)
	defer httpCtx.Release()
}

REST

Response Handler

When you call a REST endpoint, you can use SetResponseHandler to handle the response. There are a few helper methods to write handlers for different response status codes. Also, you use DefaultResponseHandler to set a default handler for all status codes, which are not handled by other handlers.

package main

import (
	"context"

	"github.com/clubpay/ronykit/kit"
	"github.com/clubpay/ronykit/stub"
)

type ErrorMessage struct {
	Message string `json:"message"`
}

type SuccessMessage struct {
	Message string `json:"message"`
}

func main() {
	ctx := context.Background()
	s := stub.New("webhook.site", stub.Secure())
	httpCtx := s.REST().
		POST("/someendPoint/slug1").
		SetHeader("Content-Type", "application/json").
		SetQuery("someKey", "someValue").
		SetResponseHandler(
			400,
			func(ctx context.Context, r stub.RESTResponse) *stub.Error {
				res := &ErrorMessage{}
				err := stub.WrapError(kit.UnmarshalMessage(r.GetBody(), res))
				if err != nil {
					return err
				}

				return stub.NewErrorWithMsg(res)
			},
		).
		DefaultResponseHandler(
			func(ctx context.Context, r stub.RESTResponse) *stub.Error {
				res := &SuccessMessage{}

				return stub.WrapError(kit.UnmarshalMessage(r.GetBody(), res))
			},
		).
		Run(ctx)
	defer httpCtx.Release()

  if httpCtx.Error() != nil {
		// handle error
	}
}

Documentation

Index

Constants

View Source 
const (
	WebsocketText   = websocket.TextMessage
	WebsocketBinary = websocket.BinaryMessage
)

Variables

View Source 
var (
	ErrBadHandshake = websocket.ErrBadHandshake

	ErrTimeout = errors.New("timeout")
)

Functions

This section is empty.

Types

type CompressionLevel 

type CompressionLevel int
const (
	CompressionBestSpeed       CompressionLevel = flate.BestSpeed
	CompressionBestCompression CompressionLevel = flate.BestCompression
)

type Dialer 

type Dialer = websocket.Dialer

type Error 

type Error struct {
	// contains filtered or unexported fields
}

func NewError 

func NewError(code int, item string) *Error

func NewErrorWithMsg 

func NewErrorWithMsg(msg kit.Message) *Error

func WrapError 

func WrapError(err error) *Error

func (Error) Code 

func (err Error) Code() int

func (Error) Error 

func (err Error) Error() string

func (Error) Is 

func (err Error) Is(target error) bool

func (Error) Item 

func (err Error) Item() string

func (Error) Msg 

func (err Error) Msg() kit.Message

func (Error) Unwrap 

func (err Error) Unwrap() error
type Header map[string]string

type OnConnectHandler 

type OnConnectHandler func(ctx *WebsocketCtx)

type Option 

type Option func(cfg *config)

func AddRootCA added in v0.16.5 

func AddRootCA(certs ...*x509.Certificate) Option

func AddRootCAFromPEM added in v0.16.5 

func AddRootCAFromPEM(pemCerts ...[]byte) Option

func DumpTo 

func DumpTo(w io.Writer) Option

func Name 

func Name(name string) Option

func Secure 

func Secure() Option

func SkipTLSVerify 

func SkipTLSVerify() Option

func WithCertificatePool added in v0.16.5 

func WithCertificatePool(certPool *x509.CertPool) Option

func WithDialTimeout 

func WithDialTimeout(timeout time.Duration) Option

func WithHTTPProxy 

func WithHTTPProxy(proxyURL string, timeout time.Duration) Option

WithHTTPProxy returns an Option that sets the dialer to the provided HTTP proxy. example formats: 

localhost:9050
username:password@localhost:9050
localhost:9050

func WithLogger 

func WithLogger(l kit.Logger) Option

func WithMessageCodec 

func WithMessageCodec(c kit.MessageCodec) Option

func WithReadTimeout 

func WithReadTimeout(timeout time.Duration) Option

func WithSocksProxy 

func WithSocksProxy(proxyURL string) Option

WithSocksProxy returns an Option that sets the dialer to the provided SOCKS5 proxy. example format: localhost:9050

func WithTracePropagator 

func WithTracePropagator(tp kit.TracePropagator) Option

func WithWriteTimeout 

func WithWriteTimeout(timeout time.Duration) Option

type PreDialHandler 

type PreDialHandler func(d *Dialer)

type RESTCtx 

type RESTCtx struct {
	// contains filtered or unexported fields
}

func HTTP 

func HTTP(rawURL string, opts ...Option) (*RESTCtx, error)

func (*RESTCtx) AppendQuery 

func (hc *RESTCtx) AppendQuery(key, value string) *RESTCtx

func (*RESTCtx) AutoRun 

func (hc *RESTCtx) AutoRun(
	ctx context.Context, route string, enc kit.Encoding, m kit.Message,
) *RESTCtx

AutoRun is a helper method, which fills the request based on the input arguments. It checks the route which is a path pattern, and fills the dynamic url params based on the `m`'s `tag` keys. Example: 

type Request struct {
		ID int64 `json:"id"`
		Name string `json:"name"`
}

AutoRun( 

	context.Background(),
  "/something/:id/:name",
  kit.JSON,
  &Request{ID: 10, Name: "customName"},

)

Is equivalent to:

SetPath("/something/10/customName"). Run(context.Background())

func (*RESTCtx) CopyBody 

func (hc *RESTCtx) CopyBody(dst []byte) []byte

CopyBody copies the body to `dst`. It creates a new slice and returns it if dst is nil.

func (*RESTCtx) DefaultResponseHandler 

func (hc *RESTCtx) DefaultResponseHandler(h RESTResponseHandler) *RESTCtx

func (*RESTCtx) DumpRequest 

func (hc *RESTCtx) DumpRequest() string

func (*RESTCtx) DumpRequestTo 

func (hc *RESTCtx) DumpRequestTo(w io.Writer) *RESTCtx

DumpRequestTo accepts a writer and will write the request dump to it when Run is executed.

Please refer to DumpResponseTo

func (*RESTCtx) DumpResponse 

func (hc *RESTCtx) DumpResponse() string

func (*RESTCtx) DumpResponseTo 

func (hc *RESTCtx) DumpResponseTo(w io.Writer) *RESTCtx

DumpResponseTo accepts a writer and will write the response dump to it when Run is executed. Example: 

httpCtx := s.REST().
							DumpRequestTo(os.Stdout).
							DumpResponseTo(os.Stdout).
							GET("https//google.com").
							Run(ctx)
defer httpCtx.Release()

**YOU MUST NOT USE httpCtx after httpCtx.Release() is called.**

func (*RESTCtx) Err 

func (hc *RESTCtx) Err() *Error

Err returns the error if any occurred during the execution.

func (*RESTCtx) Error 

func (hc *RESTCtx) Error() error

Error returns the error if any occurred during the execution.

func (*RESTCtx) GET 

func (hc *RESTCtx) GET(path string) *RESTCtx

func (*RESTCtx) GetBody 

func (hc *RESTCtx) GetBody() []byte

GetBody returns the body, but please note that the returned slice is only valid until Release is called. If you need to use the body after releasing RESTCtx then use CopyBody method.

func (*RESTCtx) GetBodyWriter added in v0.17.8 

func (hc *RESTCtx) GetBodyWriter() io.Writer

func (*RESTCtx) GetHeader 

func (hc *RESTCtx) GetHeader(key string) string

GetHeader returns the header value for the key in the response

func (*RESTCtx) GetUncompressedBody added in v0.18.3 

func (hc *RESTCtx) GetUncompressedBody() ([]byte, error)

func (*RESTCtx) OPTIONS 

func (hc *RESTCtx) OPTIONS(path string) *RESTCtx

func (*RESTCtx) PATCH 

func (hc *RESTCtx) PATCH(path string) *RESTCtx

func (*RESTCtx) POST 

func (hc *RESTCtx) POST(path string) *RESTCtx

func (*RESTCtx) PUT 

func (hc *RESTCtx) PUT(path string) *RESTCtx

func (*RESTCtx) ReadResponseBody 

func (hc *RESTCtx) ReadResponseBody(w io.Writer) *RESTCtx

ReadResponseBody reads the response body to the provided writer. It MUST be called after Run or AutoRun.

func (*RESTCtx) ReadUncompressedResponseBody added in v0.18.3 

func (hc *RESTCtx) ReadUncompressedResponseBody(w io.Writer) *RESTCtx

func (*RESTCtx) Release 

func (hc *RESTCtx) Release()

Release frees the allocated internal resources to be re-used. You MUST NOT refer to any method of this object after calling this method, if you call any method after Release has been called, the result is unpredictable.

func (*RESTCtx) Run 

func (hc *RESTCtx) Run(ctx context.Context) *RESTCtx

func (*RESTCtx) SetBody 

func (hc *RESTCtx) SetBody(body []byte) *RESTCtx

func (*RESTCtx) SetBodyErr 

func (hc *RESTCtx) SetBodyErr(body []byte, err error) *RESTCtx

SetBodyErr is a helper method, which is useful when we want to pass the marshaler function directly without checking the error, before passing it to the SetBody method. example: 

restCtx.SetBodyErr(json.Marshal(m))

Is equivalent to: 

b, err := json.Marshal(m)
if err != nil {
	// handle err
}
restCtx.SetBody(b)

func (*RESTCtx) SetContentEncoding added in v0.17.7 

func (hc *RESTCtx) SetContentEncoding(encoding string) *RESTCtx

func (*RESTCtx) SetDeflateBody added in v0.17.7 

func (hc *RESTCtx) SetDeflateBody(body []byte) *RESTCtx

func (*RESTCtx) SetDeflateBodyWithLevel added in v0.17.9 

func (hc *RESTCtx) SetDeflateBodyWithLevel(body []byte, lvl RequestCompressionLevel) *RESTCtx

func (*RESTCtx) SetGZipBody added in v0.17.8 

func (hc *RESTCtx) SetGZipBody(body []byte) *RESTCtx

func (*RESTCtx) SetGZipBodyWithLevel added in v0.17.9 

func (hc *RESTCtx) SetGZipBodyWithLevel(body []byte, lvl RequestCompressionLevel) *RESTCtx

func (*RESTCtx) SetHeader 

func (hc *RESTCtx) SetHeader(key, value string) *RESTCtx

func (*RESTCtx) SetHeaderMap 

func (hc *RESTCtx) SetHeaderMap(kv map[string]string) *RESTCtx

func (*RESTCtx) SetMethod 

func (hc *RESTCtx) SetMethod(method string) *RESTCtx

func (*RESTCtx) SetMultipartForm 

func (hc *RESTCtx) SetMultipartForm(frm *multipart.Form, boundary string) *RESTCtx

SetMultipartForm sets the body of the request to a multipart form. It will reset any previous data that was set by SetBody method.

func (*RESTCtx) SetOKHandler 

func (hc *RESTCtx) SetOKHandler(h RESTResponseHandler) *RESTCtx

func (*RESTCtx) SetPath 

func (hc *RESTCtx) SetPath(path string) *RESTCtx

func (*RESTCtx) SetPathF added in v0.17.0 

func (hc *RESTCtx) SetPathF(format string, args ...any) *RESTCtx

func (*RESTCtx) SetQuery 

func (hc *RESTCtx) SetQuery(key, value string) *RESTCtx

func (*RESTCtx) SetQueryMap 

func (hc *RESTCtx) SetQueryMap(kv map[string]string) *RESTCtx

func (*RESTCtx) SetResponseHandler 

func (hc *RESTCtx) SetResponseHandler(statusCode int, h RESTResponseHandler) *RESTCtx

func (*RESTCtx) StatusCode 

func (hc *RESTCtx) StatusCode() int

StatusCode returns the status code of the response

type RESTOption 

type RESTOption func(cfg *restConfig)

func WithHeader 

func WithHeader(key, value string) RESTOption

func WithHeaderMap 

func WithHeaderMap(hdr map[string]string) RESTOption

func WithPreflightREST 

func WithPreflightREST(h ...RESTPreflightHandler) RESTOption

WithPreflightREST register one or many handlers to run in sequence before actually making requests.

type RESTPreflightHandler 

type RESTPreflightHandler func(r *fasthttp.Request)

type RESTResponse 

type RESTResponse interface {
	StatusCode() int
	GetBody() []byte
	GetHeader(key string) string
}

type RESTResponseHandler 

type RESTResponseHandler func(ctx context.Context, r RESTResponse) *Error

type RPCContainerHandler 

type RPCContainerHandler func(ctx context.Context, c kit.IncomingRPCContainer)

type RPCMessageHandler 

type RPCMessageHandler func(ctx context.Context, msg kit.Message, hdr Header, err error)

type RPCPreflightHandler 

type RPCPreflightHandler func(req *WebsocketRequest)

type RequestCompressionLevel added in v0.17.9 

type RequestCompressionLevel int
const (
	CompressNoCompression      RequestCompressionLevel = flate.NoCompression
	CompressBestSpeed          RequestCompressionLevel = flate.BestSpeed
	CompressBestCompression    RequestCompressionLevel = flate.BestCompression
	CompressDefaultCompression RequestCompressionLevel = 6
	CompressHuffmanOnly        RequestCompressionLevel = -2
)

type Stub 

type Stub struct {
	// contains filtered or unexported fields
}

func New 

func New(hostPort string, opts ...Option) *Stub

func (*Stub) REST 

func (s *Stub) REST(opt ...RESTOption) *RESTCtx

func (*Stub) Websocket 

func (s *Stub) Websocket(opts ...WebsocketOption) *WebsocketCtx

type WebsocketCtx 

type WebsocketCtx struct {
	// contains filtered or unexported fields
}

func (*WebsocketCtx) BinaryMessage 

func (wCtx *WebsocketCtx) BinaryMessage(
	ctx context.Context, predicate string, req, res kit.Message,
	cb RPCMessageHandler,
) error

func (*WebsocketCtx) Connect 

func (wCtx *WebsocketCtx) Connect(ctx context.Context, path string) error

func (*WebsocketCtx) Disconnect 

func (wCtx *WebsocketCtx) Disconnect()

func (*WebsocketCtx) Do 

func (wCtx *WebsocketCtx) Do(ctx context.Context, req WebsocketRequest) error

Do send a message to the websocket server and waits for the response. If the callback is not nil, then make sure you provide a context with deadline or timeout, otherwise you will leak goroutines.

func (*WebsocketCtx) NetConn 

func (wCtx *WebsocketCtx) NetConn() net.Conn

NetConn returns the underlying net.Conn, ONLY for advanced use cases

func (*WebsocketCtx) Reconnect added in v0.17.10 

func (wCtx *WebsocketCtx) Reconnect(ctx context.Context) error

func (*WebsocketCtx) Stats 

func (wCtx *WebsocketCtx) Stats() WebsocketStats

func (*WebsocketCtx) TextMessage 

func (wCtx *WebsocketCtx) TextMessage(
	ctx context.Context, predicate string, req, res kit.Message,
	cb RPCMessageHandler,
) error

type WebsocketOption 

type WebsocketOption func(cfg *wsConfig)

func WithAutoReconnect 

func WithAutoReconnect(b bool) WebsocketOption

func WithCompression 

func WithCompression(c CompressionLevel) WebsocketOption

func WithConcurrency 

func WithConcurrency(n int) WebsocketOption

func WithCustomDialerBuilder 

func WithCustomDialerBuilder(b func() *websocket.Dialer) WebsocketOption

func WithCustomRPC 

func WithCustomRPC(in kit.IncomingRPCFactory, out kit.OutgoingRPCFactory) WebsocketOption

func WithDefaultHandler 

func WithDefaultHandler(h RPCContainerHandler) WebsocketOption

func WithHandler 

func WithHandler(predicate string, h RPCContainerHandler) WebsocketOption

func WithOnConnectHandler 

func WithOnConnectHandler(f OnConnectHandler) WebsocketOption

func WithPingTime 

func WithPingTime(t time.Duration) WebsocketOption

func WithPreDialHandler 

func WithPreDialHandler(f PreDialHandler) WebsocketOption

func WithPredicateKey 

func WithPredicateKey(key string) WebsocketOption

func WithPreflightRPC 

func WithPreflightRPC(h ...RPCPreflightHandler) WebsocketOption

WithPreflightRPC register one or many handlers to run in sequence before actually making requests.

func WithRecoverPanic 

func WithRecoverPanic(f func(err any)) WebsocketOption

func WithUpgradeHeader 

func WithUpgradeHeader(key string, values ...string) WebsocketOption

type WebsocketRequest 

type WebsocketRequest struct {
	// ID is optional, if you don't set it, a random string will be generated
	ID string
	// Predicate is the routing key for the message, which will be added to the kit.OutgoingRPCContainer
	Predicate string
	// MessageType is the type of the message, either websocket.TextMessage or websocket.BinaryMessage
	MessageType int
	ReqMsg      kit.Message
	// ResMsg is the message that will be used to unmarshal the response.
	// You should pass a pointer to the struct that you want to unmarshal the response into.
	// If Callback is nil, then this field will be ignored.
	ResMsg kit.Message
	// ReqHdr is the headers that will be added to the kit.OutgoingRPCContainer
	ReqHdr Header
	// Callback is the callback that will be called when the response is received.
	// If this is nil, the response will be ignored. However, the response will be caught by
	// the default handler if it is set.
	Callback RPCMessageHandler
	// Timeout if is set, then the callback will be called with ErrTimeout, in case of we didn't
	// receive the response in time.
	Timeout time.Duration
}

type WebsocketStats 

type WebsocketStats struct {
	// ReadBytes is the total number of bytes read from the current websocket connection
	ReadBytes uint64
	// ReadBytesTotal is the total number of bytes read since WebsocketCtx creation
	ReadBytesTotal uint64
	// WriteBytes is the total number of bytes written to the current websocket connection
	WriteBytes uint64
	// WriteBytesTotal is the total number of bytes written since WebsocketCtx creation
	WriteBytesTotal uint64
}

Source Files

View all Source files

Directories

Path Synopsis
internal
tpl

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.