options

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Jan 16, 2025 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidWriterType  = errors.New("invalid writer type")
	ErrMissingFilePath    = errors.New("file path must be specified when using WriteToFile")
	ErrUnexpectedFilePath = errors.New("filepath should not be provided when using WriteToBuffer")
	ErrInvalidCompression = errors.New("unsupported compression type")
)

Common errors returned by Option methods

Functions

func ProgressReader 

func ProgressReader(reader io.Reader, total int64, onProgress func(read, total int64)) *progressReader

ProgressReader creates a new progressReader to monitor reading progress. The total parameter specifies the expected total size of the data. The onProgress callback is invoked with the current and total read values.

func ProgressWriter 

func ProgressWriter(writer io.WriteCloser, total int64, onProgress func(written, total int64)) *progressWriter

ProgressWriter creates a new progressWriter to monitor writing progress. The total parameter specifies the expected total size of the data. The onProgress callback is invoked with the current and total written values.

Types

type CompressionType 

type CompressionType string

CompressionType defines the compression algorithm used for HTTP requests. It supports standard compression types (gzip, deflate, brotli) as well as custom compression implementations. 

const (
	CompressionNone    CompressionType = ""        // No compression
	CompressionGzip    CompressionType = "gzip"    // Gzip compression (RFC 1952)
	CompressionDeflate CompressionType = "deflate" // Deflate compression (RFC 1951)
	CompressionBrotli  CompressionType = "br"      // Brotli compression
	CompressionCustom  CompressionType = "custom"  // Custom compression implementation
)

Compression types supported by the client

type Option 

type Option struct {
	Verbose                  bool                                           // Whether logging should be verbose or not
	Logger                   slog.Logger                                    // Logging - default uses the slog TextHandler
	Header                   http.Header                                    // Headers to be included in the request
	Cookies                  []*http.Cookie                                 // Cookies to be included in the request
	ProtocolScheme           string                                         // define a custom protocol scheme. It defaults to https
	Compression              CompressionType                                // CompressionType to use: none, gzip, deflate or brotli
	CustomCompressionType    CompressionType                                // When using a custom compression, specify the type to be used as the content-encoding header.
	CustomCompressor         func(w *io.PipeWriter) (io.WriteCloser, error) // Function for custom compression
	UserAgent                string                                         // User Agent to send with requests
	FollowRedirect           bool                                           // Disable or enable redirects. Default is true i.e.: follow redirects
	PreserveMethodOnRedirect bool                                           // Default is true
	UniqueIdentifierType     UniqueIdentifierType                           // Internal trace or identifier for the request
	Transport                *http.Transport                                // Create our own default transport
	ResponseWriter           ResponseWriter                                 // Define the type of response writer
	UploadBufferSize         *int                                           // Control the size of the buffer when uploading a file
	DownloadBufferSize       *int                                           // Control the size of the buffer when downloading a file
	OnUploadProgress         func(bytesRead, totalBytes int64)              // To monitor and track progress when uploading
	OnDownloadProgress       func(bytesRead, totalBytes int64)              // To monitor and track progress when downloading
	// contains filtered or unexported fields
}

Option provides configuration for HTTP requests. It allows customization of various aspects of the request including headers, compression, logging, response handling, and progress tracking. If no options are provided when making a request, a default configuration is automatically generated.

func New 

func New(opts ...*Option) *Option

New creates a default Option with pre-configured settings. If additional options are provided via the variadic parameter, they will be merged with the default settings, with the provided options taking precedence.

func (*Option) AddCookie 

func (opt *Option) AddCookie(cookie *http.Cookie)

AddCookie adds a new cookie to the Option's cookie collection. If the cookie slice hasn't been initialized, it will be created.

func (*Option) AddHeader 

func (opt *Option) AddHeader(key string, value string)

AddHeader adds a new header with the specified key and value to the request headers. If the headers map hasn't been initialized, it will be created. Kept for backwards compatability

func (*Option) ClearCookies 

func (opt *Option) ClearCookies()

ClearCookies removes all previously set cookies from the Option.

func (*Option) ClearHeaders 

func (opt *Option) ClearHeaders()

ClearHeaders removes all previously set headers from the Option.

func (*Option) CreatePayloadReader added in v1.1.1 

func (opt *Option) CreatePayloadReader(payload any) (io.Reader, int64, error)

CreatePayloadReader converts the given payload into an io.Reader along with its size. Supported payload types include: - nil: Returns a nil reader and a size of -1. - []byte: Returns a bytes.Reader for the byte slice and its length as size. - io.Reader: Returns the reader and attempts to determine its size if it implements io.Seeker. - string: Returns a strings.Reader for the string and its length as size. For unsupported payload types, an error is returned.

func (*Option) DisableLogging 

func (opt *Option) DisableLogging()

DisableLogging turns off verbose logging for the Option instance.

func (*Option) DisablePreserveMethodOnRedirect 

func (opt *Option) DisablePreserveMethodOnRedirect()

DisablePreserveMethodOnRedirect configures redirects to not maintain the original HTTP method.

func (*Option) DisableRedirects 

func (opt *Option) DisableRedirects()

DisableRedirects configures the Option to not follow HTTP redirects.

func (*Option) EnableLogging 

func (opt *Option) EnableLogging()

EnableLogging turns on verbose logging for the Option instance.

func (*Option) EnablePreserveMethodOnRedirect 

func (opt *Option) EnablePreserveMethodOnRedirect()

EnablePreserveMethodOnRedirect configures redirects to maintain the original HTTP method.

func (*Option) EnableRedirects 

func (opt *Option) EnableRedirects()

EnableRedirects configures the Option to follow HTTP redirects.

func (*Option) GenerateIdentifier 

func (opt *Option) GenerateIdentifier() string

GenerateIdentifier creates a unique identifier based on the configured UniqueIdentifierType. Returns a UUID or ULID string, or an empty string if no identifier type is configured.

func (*Option) GetCompressor 

func (opt *Option) GetCompressor(w *io.PipeWriter) (io.WriteCloser, error)

GetCompressor returns an appropriate io.WriteCloser based on the configured compression type. Returns an error if the compression type is unsupported or if a custom compressor is not properly configured.

func (*Option) GetWriter 

func (opt *Option) GetWriter() io.WriteCloser

GetWriter returns the currently configured io.WriteCloser instance.

func (*Option) InferContentType added in v1.1.1 

func (opt *Option) InferContentType(file *os.File, fileInfo os.FileInfo) error

InferContentType determines the MIME type of a file based on its content and extension. If it is unable to determine a MIME type, it defaults to application/octet-stream.

func (*Option) InitialiseWriter 

func (opt *Option) InitialiseWriter() (io.WriteCloser, error)

InitialiseWriter sets up the appropriate writer based on the ResponseWriter configuration. Returns an error if the writer type is invalid or if required parameters are missing.

func (*Option) Log added in v1.1.1 

func (opt *Option) Log(msg string, args ...any)

Log logs a message with the configured logger if verbose logging is enabled. The message will be logged at INFO level with any additional arguments provided.

func (*Option) Merge 

func (opt *Option) Merge(src *Option)

Merge combines the settings from another Option instance into this one. Settings from the source Option take precedence over existing settings. This includes headers, cookies, compression settings, and all other configuration options.

func (*Option) SetBufferOutput 

func (opt *Option) SetBufferOutput()

SetBufferOutput configures the response writer to write responses to an in-memory buffer.

func (*Option) SetCompression 

func (opt *Option) SetCompression(compressionType CompressionType)

SetCompression configures the compression type to be used for the request. Valid compression types include: none, gzip, deflate, brotli, and custom.

func (*Option) SetDownloadBufferSize 

func (opt *Option) SetDownloadBufferSize(size int)

SetDownloadBufferSize configures the buffer size used when downloading files. The size must be positive; otherwise, the setting will be ignored.

func (*Option) SetFileOutput 

func (opt *Option) SetFileOutput(filepath string)

SetFileOutput configures the response writer to write responses to a file at the specified path.

func (*Option) SetLogger 

func (opt *Option) SetLogger(logger *slog.Logger)

SetLogger configures a custom logger and enables verbose logging. The provided logger will replace any existing logger configuration.

func (*Option) SetOutput 

func (opt *Option) SetOutput(writerType ResponseWriterType, filepath ...string) error

SetOutput configures how the response should be written, either to a file or buffer. For file output, a filepath must be provided. Returns an error if the configuration is invalid.

func (*Option) SetProtocolScheme 

func (opt *Option) SetProtocolScheme(scheme string)

SetProtocolScheme sets the protocol scheme (e.g., "http://", "https://") for requests. If the provided scheme doesn't end with "://", it will be automatically appended.

func (*Option) SetTransport 

func (opt *Option) SetTransport(transport *http.Transport)

SetTransport configures a custom HTTP transport for the requests. This allows fine-grained control over connection pooling, timeouts, and other transport-level settings.

func (*Option) UseJsonLogger 

func (opt *Option) UseJsonLogger()

UseJsonLogger configures the Option to use a JSON-based logger and enables verbose logging. The logger will output to stdout using the default slog JSONHandler format.

func (*Option) UseTextLogger 

func (opt *Option) UseTextLogger()

UseTextLogger configures the Option to use a text-based logger and enables verbose logging. The logger will output to stdout using the default slog TextHandler format.

type ResponseWriter 

type ResponseWriter struct {
	// Type determines the destination for response data.
	// Must be either WriteToBuffer or WriteToFile.
	Type ResponseWriterType

	// FilePath specifies the destination file path when Type is WriteToFile.
	// This field is ignored when Type is WriteToBuffer.
	// The path must be writable and will be created if it doesn't exist.
	FilePath string
	// contains filtered or unexported fields
}

ResponseWriter contains configuration for handling HTTP response bodies. It supports writing responses either to an in-memory buffer or directly to a file, allowing for flexible response handling based on the needs of the caller.

type ResponseWriterType 

type ResponseWriterType string

ResponseWriterType defines how the HTTP response body should be handled. It determines whether responses are written to an in-memory buffer or directly to a file. 

const (
	// WriteToBuffer indicates that responses should be written to an in-memory buffer.
	// This is useful for smaller responses that need to be processed in memory.
	WriteToBuffer ResponseWriterType = "buffer"

	// WriteToFile indicates that responses should be written directly to a file.
	// This is recommended for large responses to minimize memory usage.
	WriteToFile ResponseWriterType = "file"
)

Supported response writer types

type UniqueIdentifierType 

type UniqueIdentifierType string

UniqueIdentifierType defines the type of unique identifier to use for request tracing. It supports both UUID and ULID formats. 

const (
	IdentifierNone UniqueIdentifierType = ""     // No identifier
	IdentifierUUID UniqueIdentifierType = "uuid" // UUID v4
	IdentifierULID UniqueIdentifierType = "ulid" // ULID timestamp-based identifier
)

Supported identifier types for request tracing

type WriteCloserBuffer 

type WriteCloserBuffer struct {
	*bytes.Buffer
}

WriteCloserBuffer is a wrapper around bytes.Buffer that implements the io.WriteCloser interface. It is used as an in-memory buffer for writing data where closing the buffer does not require any additional cleanup or resource management.

func (*WriteCloserBuffer) Close 

func (wcb *WriteCloserBuffer) Close() error

Close satisfies the io.WriteCloser interface but performs no action. This is because there are no resources to release or clean up for an in-memory buffer.

Source Files

View all Source files

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.