Skip to content

docs: improve API comments and update copyright years #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
spiegel-im-spiegel merged 1 commit into from
May 9, 2026
Merged

docs: improve API comments and update copyright years #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions client.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,10 @@ type client struct {
client *http.Client
}

// ClientOpts configures a Client.
type ClientOpts func(*client)

// New function returns Client instance.
// New creates a new Client.
func New(opts ...ClientOpts) Client {
cli := &client{client: &http.Client{}}
for _, opt := range opts {
Expand All @@ -28,7 +29,9 @@ func New(opts ...ClientOpts) Client {
return cli
}

// WithProtocol returns function for setting http.Client.
// WithHTTPClient sets the HTTP client used by fetch.
//
// If cli is nil, it falls back to a default *http.Client.
func WithHTTPClient(cli *http.Client) ClientOpts {
return func(c *client) {
if cli == nil {
Expand All @@ -39,13 +42,13 @@ func WithHTTPClient(cli *http.Client) ClientOpts {
}
}

// Get method returns respons data from URL by GET method.
// Deprecated: Should use GetWithContext() method instead of Get() method.
// Get fetches data from URL with HTTP GET.
// Deprecated: Use GetWithContext instead.
func (c *client) Get(u *url.URL, opts ...RequestOpts) (Response, error) {
return c.GetWithContext(context.Background(), u, opts...)
}

// GetWithContext method returns respons data from URL by GET method with context.Context.
// GetWithContext fetches data from URL with HTTP GET and context.
func (c *client) GetWithContext(ctx context.Context, u *url.URL, opts ...RequestOpts) (Response, error) {
req, err := request(ctx, http.MethodGet, u, nil, opts...)
if err != nil {
Expand All @@ -61,13 +64,13 @@ func (c *client) GetWithContext(ctx context.Context, u *url.URL, opts ...Request
return resp, nil
}

// Post method returns respons data from URL by POST method.
// Deprecated: Should use PostWithContext() method instead of Post() method.
// Post fetches data from URL with HTTP POST.
// Deprecated: Use PostWithContext instead.
func (c *client) Post(u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error) {
return c.PostWithContext(context.Background(), u, payload, opts...)
}

// PostWithContext method returns respons data from URL by POST method with context.Context.
// PostWithContext fetches data from URL with HTTP POST and context.
func (c *client) PostWithContext(ctx context.Context, u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error) {
req, err := request(ctx, http.MethodPost, u, payload, opts...)
if err != nil {
Expand All @@ -83,8 +86,8 @@ func (c *client) PostWithContext(ctx context.Context, u *url.URL, payload io.Rea
return resp, nil
}

// WithProtocol returns function for setting context.Context.
// Deprecated: should not be used
// WithContext sets request context on an option-applied request.
// Deprecated: Use GetWithContext and PostWithContext instead.
func WithContext(ctx context.Context) RequestOpts {
return func(req *http.Request) *http.Request {
if ctx != nil {
Expand All @@ -110,6 +113,7 @@ func WithRequestHeaderSet(name, value string) RequestOpts {
}
}

// request creates an HTTP request and applies request options.
func request(ctx context.Context, method string, u *url.URL, payload io.Reader, opts ...RequestOpts) (*http.Request, error) {
if u == nil {
return nil, errs.Wrap(ErrInvalidURL)
Expand All @@ -124,6 +128,7 @@ func request(ctx context.Context, method string, u *url.URL, payload io.Reader,
return req, nil
}

// fetch sends the request and validates response status.
func (c *client) fetch(request *http.Request) (Response, error) {
if c == nil {
c = New().(*client)
Expand All @@ -146,6 +151,7 @@ func (c *client) fetch(request *http.Request) (Response, error) {
return resp, nil
}

// urlText returns a string form of URL, or an empty string for nil URL.
func urlText(u *url.URL) string {
if u == nil {
return ""
Expand Down
12 changes: 8 additions & 4 deletions errors.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,17 @@ package fetch
import "errors"

var (
ErrNullPointer = errors.New("null reference instance")
// ErrNullPointer indicates a nil receiver or nil embedded value access.
ErrNullPointer = errors.New("null reference instance")
// ErrInvalidRequest indicates a request construction or execution failure.
ErrInvalidRequest = errors.New("invalid HTTP request")
ErrInvalidURL = errors.New("invalid URL")
ErrHTTPStatus = errors.New("bad HTTP status")
// ErrInvalidURL indicates an invalid URL input.
ErrInvalidURL = errors.New("invalid URL")
// ErrHTTPStatus indicates non-success HTTP status.
ErrHTTPStatus = errors.New("bad HTTP status")
)

/* Copyright 2021 Spiegel
/* Copyright 2021-2026 Spiegel
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down
23 changes: 18 additions & 5 deletions fetch.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,41 @@ import (
"net/url"
)

// RequestOpts applies options to an HTTP request.
//
// The returned request value allows option functions to replace the request,
// for example when changing context with req.WithContext.
type RequestOpts func(*http.Request) *http.Request

// Client is inteface class for HTTP client.
// Client represents a fetch client.
type Client interface {
// Deprecated: Should use GetWithContext() method instead of Get() method.
// Get sends a GET request.
// Deprecated: Use GetWithContext instead.
Get(u *url.URL, opts ...RequestOpts) (Response, error)
// GetWithContext sends a GET request with context.
GetWithContext(ctx context.Context, u *url.URL, opts ...RequestOpts) (Response, error)
// Deprecated: Should use PostWithContext() method instead of Post() method.
// Post sends a POST request.
// Deprecated: Use PostWithContext instead.
Post(u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error)
// PostWithContext sends a POST request with context.
PostWithContext(ctx context.Context, u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error)
}

// Response is inteface class for HTTP response.
// Response wraps an HTTP response.
type Response interface {
// Request returns the original request.
Request() *http.Request
// Header returns response headers.
Header() http.Header
// Body returns the response body reader.
Body() io.ReadCloser
// Close drains and closes the response body.
Close() error
// DumpBodyAndClose reads all body bytes and closes the response body.
DumpBodyAndClose() ([]byte, error)
}

/* Copyright 2023-2025 Spiegel
/* Copyright 2023-2026 Spiegel
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down
7 changes: 4 additions & 3 deletions response.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import (
"github.com/goark/errs"
)

// response is wrapper class of http.Response.
// response wraps http.Response.
type response struct {
*http.Response
}
Expand All @@ -29,15 +29,15 @@ func (resp *response) Header() http.Header {
return resp.Response.Header
}

// Header method returns Body element in http.Response.
// Body method returns Body element in http.Response.
func (resp *response) Body() io.ReadCloser {
if resp == nil || resp.Response == nil {
return nil
}
return resp.Response.Body
}

// Close method closes Response.Body safety.
// Close method safely drains and closes Response.Body.
func (resp *response) Close() (err error) {
if resp == nil || resp.Response == nil {
return nil
Expand All @@ -56,6 +56,7 @@ func (resp *response) Close() (err error) {
return
}

// DumpBodyAndClose reads all response body bytes and closes Response.Body.
func (resp *response) DumpBodyAndClose() (b []byte, err error) {
if resp == nil || resp.Response == nil {
err = errs.Wrap(ErrNullPointer)
Expand Down
6 changes: 4 additions & 2 deletions url.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ import (
"github.com/goark/errs"
)

// URL function returns url.URL instance from string.
// URL parses rawURL and returns *url.URL.
//
// Leading and trailing whitespaces are trimmed before parsing.
func URL(rawURL string) (*url.URL, error) {
u, err := url.Parse(strings.TrimSpace(rawURL))
if err != nil {
Expand All @@ -16,7 +18,7 @@ func URL(rawURL string) (*url.URL, error) {
return u, nil
}

/* Copyright 2021 Spiegel
/* Copyright 2021-2026 Spiegel
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down
Loading