options

package
v2.1.1 Latest Latest
Warning

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

 Go to latest Published: Feb 5, 2025 License: MIT Imports: 20 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 NewProgressReader 

func NewProgressReader(r io.Reader, totalSize int64, onProgress func(current, total int64)) io.Reader

NewProgressReader returns an io.Reader that reports progress during read operations. If totalSize is <= 0, it attempts to determine size using io.Seeker if available. The onProgress callback receives current bytes read and total size (-1 if unknown).

func NewProgressWriter added in v2.1.0 

func NewProgressWriter(w io.Writer, totalSize int64, onProgress func(current, total int64)) io.Writer

NewProgressWriter returns an io.Writer that tracks progress during write operations. The onProgress callback is invoked with current bytes written and total size. Use for scenarios like download progress tracking.

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
	CustomDecompressor       func(r io.Reader) (io.Reader, error)           // Function for custom decompression
	UserAgent                string                                         // User Agent to send with requests
	FollowRedirects          bool                                           // Disable or enable redirects. Default is false i.e.: follow redirects
	PreserveMethodOnRedirect bool                                           // Default is false
	MaxRedirects             int                                            // Maximum number of redirects that can happen before the client gives up

	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) *Option

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) *Option

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) CheckRedirects 

func (opt *Option) CheckRedirects() bool

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) CloseFile 

func (opt *Option) CloseFile() error

CloseFile closes the currently open file if one exists and resets related metadata. It logs the closure through the configured logger and returns any error encountered during closing. After closing, the file pointer is set to nil and the filesize is reset to 0.

func (*Option) CreatePayloadReader 

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() *Option

DisablePreserveMethodOnRedirect configures redirects to not maintain the original HTTP method.

func (*Option) DisableRedirects 

func (opt *Option) DisableRedirects() *Option

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() *Option

EnablePreserveMethodOnRedirect configures redirects to maintain the original HTTP method.

func (*Option) EnableRedirects 

func (opt *Option) EnableRedirects() *Option

EnableRedirects configures the Option to follow HTTP redirects.

func (*Option) Filesize 

func (opt *Option) Filesize() int64

Filesize returns the size in bytes of the currently configured file. Returns 0 if no file is set or if the file size could not be determined. This value is set when the file is initially prepared or set.

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) GetClient 

func (opt *Option) GetClient() *http.Client

GetClient returns the HTTP client to be used for requests. If a custom client has been set via SetClient, that client is returned. Otherwise, returns a new default http.Client instance.

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.

func (*Option) GetDecompressor added in v2.1.0 

func (opt *Option) GetDecompressor(r io.ReadCloser, encoding string) (io.ReadCloser, error)

GetDecompressor returns an appropriate io.Reader for the given encoding.

func (*Option) GetFile 

func (opt *Option) GetFile() *os.File

GetFile returns the currently configured *os.File, if any. Returns nil if no file has been set. The returned file may be either opened or closed depending on the stage of request processing.

func (*Option) GetMaxRedirects 

func (opt *Option) GetMaxRedirects() int

func (*Option) GetProgressTracking added in v2.1.0 

func (opt *Option) GetProgressTracking() ProgressTracking

GetProgressTracking returns the current progress tracking setting.

func (*Option) GetWriter 

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

GetWriter returns the currently configured io.WriteCloser instance.

func (*Option) HasFileHandle 

func (opt *Option) HasFileHandle() bool

HasFileHandle returns true if there is currently a file configured for use with this Option instance. This can be used to check if file operations should be performed during request processing.

func (*Option) InferContentType 

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 

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) PrepareFile 

func (opt *Option) PrepareFile(filename string) error

PrepareFile sets up a file for upload by opening it, checking its existence, setting metadata like size and content type, and configuring appropriate headers. It takes a filename string as input and returns an error if the file cannot be accessed, doesn't exist, or fails to open. The method also automatically sets Content-Disposition headers appropriate for file uploads.

func (*Option) Redirects 

func (opt *Option) Redirects(enabled bool, preserve bool, max int) *Option

Redirects configures HTTP redirect behavior. enabled - whether to follow redirects preserve - whether to preserve the original HTTP method on redirect max - maximum number of redirects to follow (defaults to 5 if 0)

func (*Option) ReopenFile 

func (opt *Option) ReopenFile() (*os.File, error)

ReopenFile attempts to reopen a previously closed file using the stored filename. This is particularly useful during redirect handling when a file needs to be re-read. Returns the reopened file and any error encountered. Logs the reopening attempt through the configured logger.

func (*Option) SetBufferOutput 

func (opt *Option) SetBufferOutput()

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

func (*Option) SetClient 

func (opt *Option) SetClient(client *http.Client)

SetClient configures a custom HTTP client to be used for requests. This client will be used instead of the default client for all subsequent requests made with this Option instance. The provided client should be configured with any desired settings (timeouts, transport, etc) before being set.

func (*Option) SetCompression 

func (opt *Option) SetCompression(compressionType CompressionType) *Option

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) SetFile 

func (opt *Option) SetFile(file *os.File)

SetFile configures an already-opened file for use with the client. It takes an *os.File pointer and sets internal metadata like filename and filesize. Unlike PrepareFile, this method assumes the file is already opened and valid. If file stats cannot be read, the method will silently fail rather than return an error.

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) SetMaxRedirects 

func (opt *Option) SetMaxRedirects(size int) *Option

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) TrackAfterCompression added in v2.1.0 

func (opt *Option) TrackAfterCompression() *Option

TrackAfterCompression sets progress tracking to occur after data compression. This tracks actual transfer size but not original data size.

func (*Option) TrackBeforeCompression added in v2.1.0 

func (opt *Option) TrackBeforeCompression() *Option

TrackBeforeCompression sets progress tracking to occur before data compression. This tracks the original data size but may not reflect final transfer size.

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) UsePerRequestClient added in v2.1.0 

func (opt *Option) UsePerRequestClient()

UsePerRequestClient disables the use of the shared HTTP client for this Option instance. This creates a new client for each request, providing better isolation at the cost of performance. Use this when you need complete isolation between requests or when you want to customize client behavior for specific requests without affecting other requests. UsePerRequestClient disables shared client and ensures a new client is created

func (*Option) UseSharedClient added in v2.1.0 

func (opt *Option) UseSharedClient()

UseSharedClient enables the use of the shared HTTP client for this Option instance. Using a shared client provides better performance through connection pooling and reuse, especially when making multiple requests to the same host. This is the default behavior. The shared client is thread-safe and can be used concurrently across multiple goroutines.

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 ProgressTracking added in v2.1.0 

type ProgressTracking int
const (
	TrackBeforeCompression ProgressTracking = iota
	TrackAfterCompression
)

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
	IdentifierRGS  UniqueIdentifierType = "rgs"  // Randomly generated string
)

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.

func (*WriteCloserBuffer) IsEmpty 

func (w *WriteCloserBuffer) IsEmpty() bool

Determine if the bytes.Buffer is empty

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.