Documentation
¶
Overview ¶
Package client is the official HTTP client for gst backends, designed as the client-side pairing of the framework's DSL: every interface shape a model's Design() can declare has a first-class counterpart here.
DSL declaration client entry
----------------------------------- ------------------------------------------
Create/Update/Patch/Delete/Get/List verb methods (Post/Put/Patch/Delete/Get)
Payload[*XxxReq]() the verb method payload argument
Result[*XxxRsp]() the RSP type parameter, decoded from data
Route("xxx/:id/action") method + path composition
batch actions (items/ids bodies) verbs + BatchItems/BatchIDs on /batch
Export() Download
Import() Upload
SSE responses Stream
model.Pagination / Query / Cursor WithPage/WithSortBy/WithExpand/WithCursor
envelope (code/msg/data/trace_id) Envelope on success, *Error on rejection
Evolution rule: whenever the DSL grows a new action or protocol shape, this package must grow the matching entry in the same change; a DSL capability without a client counterpart is an incomplete feature.
API shape: every entry is a method on Client. The verbs whose result needs a type parameter (Get/Post/Put/Patch/Delete) are parameterized methods, so a call reads cli.Get[XxxRsp](path); entries that need no type parameter (Do, Download, Upload, Stream) are plain methods.
Index ¶
- Variables
- type Attachment
- type Client
- func (c *Client) Delete[RSP any](path string, payload any, opts ...RequestOption) (*RSP, error)
- func (c *Client) Do(method, path string, payload any, opts ...RequestOption) (*Envelope, error)
- func (c *Client) Download(path string, opts ...RequestOption) (*Attachment, error)
- func (c *Client) Get[RSP any](path string, opts ...RequestOption) (*RSP, error)
- func (c *Client) Patch[RSP any](path string, payload any, opts ...RequestOption) (*RSP, error)
- func (c *Client) Post[RSP any](path string, payload any, opts ...RequestOption) (*RSP, error)
- func (c *Client) Put[RSP any](path string, payload any, opts ...RequestOption) (*RSP, error)
- func (c *Client) Stream(method, path string, payload any, callback StreamCallback) error
- func (c *Client) Upload(path, filename string, content io.Reader, fields map[string]string) (*Envelope, error)
- type Envelope
- type Error
- type IDsPayload
- type ItemsPayload
- type ListResult
- type Option
- func WithBasicAuth(username, password string) Option
- func WithCookie(cookie *http.Cookie) Option
- func WithDebug() Option
- func WithHTTPClient(client *http.Client) Option
- func WithHeader(header http.Header) Option
- func WithLogger(logger types.Logger) Option
- func WithTimeout(timeout time.Duration) Option
- func WithToken(token string) Option
- func WithUserAgent(userAgent string) Option
- type RequestOption
- func WithCursor(field, value string, next bool) RequestOption
- func WithExpand(expand string, depth uint) RequestOption
- func WithPage(page, size int) RequestOption
- func WithQuery(keyValues ...any) RequestOption
- func WithSortBy(sortBy string) RequestOption
- func WithTimeRange(column string, from, to time.Time) RequestOption
- type StreamCallback
Constants ¶
This section is empty.
Variables ¶
var ErrStopStream = errors.New("stop consuming the stream")
ErrStopStream stops consuming the stream without reporting a failure: a callback returns it once it has seen enough events, and Stream answers nil. Tests asserting on the first few events of an endless stream are the typical user.
Functions ¶
This section is empty.
Types ¶
type Attachment ¶
type Attachment struct {
Name string // file name parsed from Content-Disposition
ContentType string
Content []byte
}
Attachment is one downloaded file attachment.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a service-level HTTP client for one gst backend: it carries the base address, the connection with its cookie jar, credentials and shared headers. Per-request state (path, payload, query parameters) is passed per call, so one client serves every endpoint of the service and can be reused across requests safely.
func New ¶
New creates a new client instance with given service base address and options. The address must start with "http://" or "https://". The client owns an isolated http.Client with its own cookie jar, so a login response cookie is carried on every later request automatically.
func (*Client) Delete ¶
Delete sends a DELETE request and decodes the envelope data into RSP. It pairs the DSL Delete action; the payload covers the standard batch delete body, deleting by id passes nil.
func (*Client) Do ¶
Do sends one request and parses the response envelope. It is the non-generic floor under the verb functions: use it when the caller needs envelope details such as TraceID or Cookies instead of a decoded payload.
func (*Client) Download ¶
func (c *Client) Download(path string, opts ...RequestOption) (*Attachment, error)
Download sends a GET request and reads the response as a file attachment, pairing the framework's Export action. A rejection answers with the regular JSON envelope and surfaces as an *Error.
func (*Client) Get ¶
func (c *Client) Get[RSP any](path string, opts ...RequestOption) (*RSP, error)
Get sends a GET request and decodes the envelope data into RSP. GET carries no request body, matching the framework contract that the List and Get actions declare no Payload.
func (*Client) Patch ¶
Patch sends a PATCH request and decodes the envelope data into RSP. It pairs the DSL Patch action and the standard batch patch route.
func (*Client) Post ¶
Post sends a POST request and decodes the envelope data into RSP. It pairs the DSL Create action and the POST-shaped custom action routes.
func (*Client) Put ¶
Put sends a PUT request and decodes the envelope data into RSP. It pairs the DSL Update action and the standard batch update route.
func (*Client) Stream ¶
func (c *Client) Stream(method, path string, payload any, callback StreamCallback) error
Stream sends the request and consumes the response as a Server-Sent Events stream, pairing the framework's SSE responses. The stream ends when the server closes the connection or the callback returns an error. A JSON answer on a stream endpoint is parsed as the regular envelope: a rejection surfaces as *Error, a success returns nil without events.
type Envelope ¶
type Envelope struct {
Code int `json:"code,omitempty"`
Msg string `json:"msg,omitempty"`
Data json.RawMessage `json:"data,omitempty"`
TraceID string `json:"trace_id,omitempty"`
Cookies []*http.Cookie `json:"-"`
}
Envelope is the standard response envelope a gst backend answers with. The verb functions decode its Data field into the business RSP type; Envelope itself is returned by Do for callers that need the envelope details, such as TraceID or the response cookies.
type Error ¶
type Error struct {
StatusCode int // HTTP status code of the response
Code int // business code from the response envelope
Msg string // business message from the response envelope
TraceID string // trace id from the response envelope
Body []byte // raw response body, kept for debugging
}
Error is a structured server-side rejection: the HTTP layer answered with a non-2xx status, or the response envelope carried a non-zero business code. Transport failures (connection refused, timeout) stay ordinary errors and never become an *Error.
type IDsPayload ¶
type IDsPayload struct {
IDs []string `json:"ids"`
}
IDsPayload is the request body of the standard batch delete route.
func BatchIDs ¶
func BatchIDs(ids []string) IDsPayload
BatchIDs builds the ids body for the standard batch delete route.
type ItemsPayload ¶
type ItemsPayload[T any] struct { Items []T `json:"items"` }
ItemsPayload is the request body of the standard batch create, update and patch routes.
func BatchItems ¶
func BatchItems[T any](items []T) ItemsPayload[T]
BatchItems builds the items body for the standard /batch routes.
type ListResult ¶
ListResult is the response envelope of the framework's standard List action. Custom list responses with extra fields decode into their own RSP type instead; nothing forces this shape on them.
type Option ¶
type Option func(*Client)
func WithBasicAuth ¶
func WithCookie ¶
WithCookie adds a cookie to the client request headers.
func WithHTTPClient ¶
func WithHeader ¶
WithHeader merges the given headers into the client defaults. A key present in header replaces the default value of that key; other defaults stay.
func WithLogger ¶
func WithTimeout ¶
func WithUserAgent ¶
type RequestOption ¶
type RequestOption func(*requestConfig)
RequestOption populates per-request state such as query parameters. Options are per call: the client instance itself stays free of request state.
func WithCursor ¶
func WithCursor(field, value string, next bool) RequestOption
WithCursor sets the framework cursor pagination parameters (_cursor_field, _cursor_value, _cursor_next).
func WithExpand ¶
func WithExpand(expand string, depth uint) RequestOption
WithExpand sets the framework association expansion parameters (_expand, _depth).
func WithPage ¶
func WithPage(page, size int) RequestOption
WithPage sets the framework offset pagination parameters (_page, _size).
func WithQuery ¶
func WithQuery(keyValues ...any) RequestOption
WithQuery adds free-form query parameters from alternating key/value pairs. Values may be strings, integers, floats or booleans; a trailing key without a value is dropped. Business filters, including the "field[op]=value" operator syntax, go through here.
func WithSortBy ¶
func WithSortBy(sortBy string) RequestOption
WithSortBy sets the framework sorting parameter (_sort_by).
func WithTimeRange ¶
func WithTimeRange(column string, from, to time.Time) RequestOption
WithTimeRange adds the framework's time-window filter on column, encoded in the "field[op]=value" operator syntax as column[gte] and column[lte]. Bounds are formatted as RFC3339, the only layout the framework accepts for URL time filtering. A zero time leaves that bound unset; a blank column adds nothing.
type StreamCallback ¶
StreamCallback handles one SSE event; returning an error stops the stream. Returning ErrStopStream stops it without surfacing an error.
Source Files