requests

Documentation

Overview

Upstream HTTP response caching.

Package requests implements handling for HTTP requests.

Common types

Index

• Constants
• func Do(ctx context.Context, opts RequestOptions) (*http.Response, []byte, error)
• func Get(ctx context.Context, url string, cookies map[string]string, ...) (io.Reader, error)
• func GetJSONBody(ctx context.Context, url string, cookies map[string]string, ...) ([]byte, error)
• func InvalidateURLs(urlPrefixes []string) (int, []string)
• func PostJSONBody(ctx context.Context, url string, payload any, cookies map[string]string, ...) ([]byte, error)
• func ProxyHandler(w http.ResponseWriter, r *http.Request, baseURL string) error
• func Setup()
• type APIError
  • func (e *APIError) Error() string
  • func (e *APIError) Unwrap() error
• type RequestOptions

Constants

const (
	// RandomToken uses a randomly generated token.
	RandomToken = "RandomToken"

	// NoToken doesn't set PHPSESSID at all.
	NoToken = "NoToken"
)

Functions

func Do

func Do(ctx context.Context, opts RequestOptions) (*http.Response, []byte, error)

Do sends an HTTP request and returns the raw *http.Response and the response body as a byte slice.

This function handles the full lifecycle of an HTTP request, including caching, authentication, and logging. It returns the raw *http.Response and the response body as a slice of bytes.

The `Body` field of the returned `*http.Response` is a `NopCloser` over these same bytes for convenience, but callers should prefer using the byte slice directly.

This function does not check for non-OK status codes, leaving that task to the caller.

func Get

func Get(
	ctx context.Context,
	url string,
	cookies map[string]string,
	incomingHeaders http.Header,
) (io.Reader, error)

Get performs a GET request and wraps the returned response.Body in a bytes.Reader.

func GetJSONBody

func GetJSONBody(
	ctx context.Context,
	url string,
	cookies map[string]string,
	incomingHeaders http.Header,
) ([]byte, error)

GetJSONBody makes a GET request and extracts the JSON payload from the response.

For standard API responses, it returns the content of the `body` field. For non-standard JSON responses (like from `/rpc/cps.php`) that do not contain an `error` or `body` field, it gracefully returns the entire response as the payload.

Returns an error if:

• The request fails
• The response contains invalid JSON
• The "error" field is a boolean true

func InvalidateURLs

func InvalidateURLs(urlPrefixes []string) (int, []string)

InvalidateURLs removes all cached items where the cached URL starts with any of the provided URL prefixes.

Takes a slice of URL prefixes to invalidate and returns the number of cache entries removed and their full URLs. Safe to call even if caching is disabled. If urls slice is nil or empty, returns 0 and an empty string slice.

cache.Contains isn't used as we don't actually know which cache key to look for due to how generateCacheKey() works

Scoping invalidation to a specific user's context is possible (e.g. per user ID), but offers little benefit for the additional complexity it introduces: how many users with different auth states are realistically hitting similar endpoints for it to matter?

func PostJSONBody

func PostJSONBody(
	ctx context.Context,
	url string,
	payload any,
	cookies map[string]string,
	csrf string,
	contentType string,
	incomingHeaders http.Header,
) ([]byte, error)

PostJSONBody performs a POST request and extracts the JSON payload from the response.

For standard API responses, it returns the content of the `body` field. It handles API-level errors where the HTTP status is 200 OK but the JSON payload contains `{"error": true}`. For streaming, use Perform() instead.

Returns an error if:

• The request fails (e.g., network error, non-2xx status code).
• The response contains invalid JSON.
• The "error" field in the JSON response is `true`.

func ProxyHandler

func ProxyHandler(w http.ResponseWriter, r *http.Request, baseURL string) error

ProxyHandler proxies a request to the specified base URL.

NOTE: We intentionally don't copy headers from the response.

func Setup

func Setup()

Setup initializes the API response cache based on parameters in GlobalConfig.

It sets up an LRU cache with a specified size and logs the cache parameters. If caching is disabled in the configuration, it skips initialization.

Types

type APIError

type APIError struct {
	// StatusCode is the HTTP status code from the response.
	// Always >= 400 for API errors.
	StatusCode int

	// Message contains the error message from the API response.
	// Empty for internal request errors, populated for API errors.
	Message string

	// Err is the underlying error cause.
	// Set to errAPIResponseError for API errors, or the original error for internal failures.
	Err error
}

APIError represents an error returned from the pixiv API or internal request handling.

func (*APIError) Error

func (e *APIError) Error() string

Error returns a formatted error message including the status code and API message if available.

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

Unwrap returns the underlying error for use with errors.Is and errors.As.

type RequestOptions

type RequestOptions struct {
	Method          string
	URL             string
	Cookies         map[string]string
	IncomingHeaders http.Header
	Payload         any
	CSRF            string
	ContentType     string
}

RequestOptions consolidates all parameters for handleRequest.