http

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2024 License: MIT Imports: 16 Imported by: 4

README

http

http defines an HTTP client implementation. It is a thin wrapper around the Go standard package net/http but in Python requests style.

Functions

call(method, url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP request of the specified method, returning a response. The call method allows for flexibility in making HTTP requests by specifying the HTTP method as an argument. It supports all common HTTP methods. This method dynamically dispatches the request based on the provided method name. It is a convenience wrapper that enables users to use any supported HTTP method without needing separate method calls for each type of request.

Parameters
name type description
method string The HTTP method to use for the request (e.g., GET, POST, PUT, DELETE).
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
form_body dict optional. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
json_body any optional. JSON data to supply as a request. handy for working with JSON-API's.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
get(url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP GET request, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
put(url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP PUT request, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
post(url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP POST request, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
postForm(url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP POST request with form data, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
delete(url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP DELETE request, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
patch(url, params=None, headers=None, auth=(), body=None, json_body=None, form_body=None, form_encoding="", timeout=30, allow_redirects=True, verify=True) response

Perform an HTTP PATCH request, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
options(url,params={},headers={},body="",form_body={},form_encoding="",json_body={},auth=(),timeout=30,allow_redirects=True,verify=True) response

Perform an HTTP OPTIONS request, returning a response.

Parameters
name type description
url string URL to request.
params dict optional. dictionary of URL parameters to append to the request.
headers dict optional. dictionary of headers to add to request.
body string optional. raw string body to provide to the request.
json_body any optional. considered only if body is None. JSON data to supply as a request. handy for working with JSON-API's.
form_body dict optional. considered only if both body and json_body are None. dict of values that will be encoded as form data. the value can be a string or a list of two strings (filename, file content) for file attachments.
form_encoding string optional. application/x-www-form-urlencoded (default for form data) or multipart/form-data.
auth tuple optional. (username,password) tuple for HTTP Basic authorization.
timeout float optional. how many seconds to wait for the server to send all the data before giving up. 0 means no timeout.
allow_redirects bool optional. whether to follow redirects.
verify bool optional. whether to verify the server's SSL certificate.
set_timeout(timeout)

Set the global timeout for all HTTP requests.

Parameters
name type description
timeout float The timeout in seconds. Must be non-negative. This timeout will be used for all subsequent HTTP requests made by the module.
get_timeout() float

Get the current global timeout setting for HTTP requests. returns: The current timeout in seconds used for HTTP requests.

Types

response

The result of performing a HTTP request.

Fields

name type description
url string the URL that was ultimately requested (may change after redirects).
status_code int response status code (for example: 200 == OK).
headers dict dictionary of response headers.
encoding string transfer encoding. example: "octet-stream" or "application/json".

Methods

body() string

output response body as a string.

json() object

attempt to parse response body as json, returning a JSON-decoded result, or None if the response body is empty or not valid JSON.

ExportedServerRequest

Encapsulates HTTP request data in a format accessible to both Go code and Starlark scripts.

Fields

name type description
method string The HTTP method (e.g., GET, POST, PUT, DELETE)
url string The request URL.
proto string The protocol used for the request (e.g., HTTP/1.1).
host string The host specified in the request.
remote string The remote address of the client.
headers dict The HTTP headers included in the request.
query dict The query parameters included in the request.
encoding []string The transfer encodings specified in the request.
body string The request body data
json any The request body data as JSON, or None if the request body is empty or not valid JSON.
ServerResponse

Enables HTTP response manipulation within Starlark scripts, facilitating dynamic preparation of HTTP responses in Go-based web servers.

Methods

set_status(code int)

Sets the HTTP status code for the response.

set_code(code int)

Alias for set_status.

add_header(key string, value string)

Adds a header with the given key and value to the response.

set_content_type(content_type string)

Sets the Content-Type header for the response, it will overwrite any existing or implicit Content-Type header.

set_data(data string|bytes)

Sets the response data as binary data, and the Content-Type header to application/octet-stream.

set_json(data any)

Sets the response data as JSON, marshaling the given Starlark value to JSON, and the Content-Type header to application/json.

set_text(data string|bytes)

Sets the response data as plain text, and the Content-Type header to text/plain.

set_html(data string|bytes)

Sets the response data as HTML, and the Content-Type header to text/html.

Documentation

Overview

Package http provides tools for integrating HTTP request handling within Go-based web servers and clients with Starlark scripting capabilities. This enables dynamic inspection and modification of HTTP requests and responses through scripts, enhancing flexibility and control over processing.

Migrated from: https://github.com/qri-io/starlib/tree/master/http with modifications.

Index

Constants

View Source 
const ModuleName = "http"

ModuleName defines the expected name for this Module when used in starlark's load() function, eg: load('http', 'get')

Variables

View Source 
var (
	// UserAgent is the default user agent for http requests, override with a custom value before calling LoadModule.
	UserAgent = "Starlet-http-client/" + itn.StarletVersion
	// TimeoutSecond is the default timeout in seconds for http requests, override with a custom value before calling LoadModule.
	TimeoutSecond = 30.0
	// SkipInsecureVerify controls whether to skip TLS verification, override with a custom value before calling LoadModule.
	SkipInsecureVerify = false
	// DisableRedirect controls whether to follow redirects, override with a custom value before calling LoadModule.
	DisableRedirect = false
	// Client is the http client used to create the http module, override with a custom client before calling LoadModule.
	Client *http.Client
	// Guard is a global RequestGuard used in LoadModule, override with a custom implementation before calling LoadModule.
	Guard RequestGuard
	// ConfigLock is a global lock for settings, use it to ensure thread safety when setting.
	ConfigLock sync.RWMutex
)

Functions

func AsString 

func AsString(x starlark.Value) (string, error)

AsString unquotes a starlark string value

func ConvertServerRequest added in v0.0.11 

func ConvertServerRequest(r *http.Request) *starlarkstruct.Struct

ConvertServerRequest converts a http.Request to a Starlark struct for use in Starlark scripts on the server side.

func LoadModule 

func LoadModule() (starlark.StringDict, error)

LoadModule creates an http Module

Types

type ExportedServerRequest added in v0.0.15 

type ExportedServerRequest struct {
	Method   string         // The HTTP method (e.g., GET, POST, PUT, DELETE)
	URL      *url.URL       // The request URL
	Proto    string         // The protocol used for the request (e.g., HTTP/1.1)
	Host     string         // The host specified in the request
	Remote   string         // The remote address of the client
	Header   http.Header    // The HTTP headers included in the request
	Encoding []string       // The transfer encodings specified in the request
	Body     []byte         // The request body data
	JSONData starlark.Value // The request body data as Starlark value
}

ExportedServerRequest encapsulates HTTP request data in a format accessible to both Go code and Starlark scripts. This struct bridges Go's HTTP handling features with Starlark's dynamic scripting capabilities, enabling seamless interaction and manipulation of request properties in Go, while providing a structured, read-only view of the request data to Starlark scripts.

Key Features:

  • Full access to HTTP request properties (method, URL, headers, body) for reading and modification in Go.
  • Structured, read-only representation of request data for Starlark scripts, enhancing scripting flexibility.
  • JSON body support simplifies working with JSON payloads directly in scripts.

Usage Pattern:

  1. Convert an incoming http.Request to ExportedServerRequest with NewExportedServerRequest for access in Go.
  2. Modify the ExportedServerRequest properties as needed in Go before handing off to Starlark.
  3. Use the Struct method to convert the ExportedServerRequest to a Starlark struct, passing it to Starlark scripts for read-only access. This step allows scripts to inspect the request's properties.
  4. Since the Starlark struct is read-only, modifications to the request must be performed in Go, either before or after script execution.

This design prioritizes ease of use, security, and performance, facilitating dynamic and complex request processing logic through Go and Starlark. It ensures the integrity of the HTTP request handling by preventing unauthorized modifications and protecting against potential security threats. Developers are encouraged to validate all modifications and interactions with the request data to maintain the server's security posture.

func NewExportedServerRequest added in v0.0.15 

func NewExportedServerRequest(r *http.Request) (*ExportedServerRequest, error)

NewExportedServerRequest creates a new ExportedServerRequest from an http.Request.

func (*ExportedServerRequest) Struct added in v0.0.15 

func (r *ExportedServerRequest) Struct() *starlarkstruct.Struct

Struct returns a Starlark struct representation of the ExportedServerRequest, which exposes the following fields to Starlark scripts:

  • method: The HTTP method (e.g., GET, POST, PUT, DELETE)
  • url: The request URL
  • proto: The protocol used for the request (e.g., HTTP/1.1)
  • host: The host specified in the request
  • remote: The remote address of the client
  • headers: The HTTP headers included in the request
  • query: The query parameters included in the request URL
  • encoding: The transfer encodings specified in the request
  • body: The request body data
  • json: The request body data as Starlark value, if it is valid JSON or None otherwise

func (*ExportedServerRequest) Write added in v0.0.15 

func (r *ExportedServerRequest) Write(req *http.Request) (err error)

Write writes the request data back to a provided http.Request instance.

type ExportedServerResponse added in v0.0.11 

type ExportedServerResponse struct {
	StatusCode int         // StatusCode is the status code of the response.
	Header     http.Header // Header is the header of the response, a map of string to list of strings. Content-Type is set automatically.
	Data       []byte      // Data is the data of the response, usually the body content.
}

ExportedServerResponse is a struct to export the response data to Go.

func (*ExportedServerResponse) Write added in v0.0.14 

func (d *ExportedServerResponse) Write(w http.ResponseWriter) (err error)

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module defines the actual HTTP module with methods for making requests.

func NewModule added in v0.1.0 

func NewModule() *Module

NewModule creates a new http module with default settings.

func (*Module) LoadModule added in v0.1.0 

func (m *Module) LoadModule() (starlark.StringDict, error)

LoadModule creates an http Module.

func (*Module) SetClient added in v0.1.0 

func (m *Module) SetClient(c *http.Client)

SetClient sets the http client for this module, useful for setting custom clients for testing or multiple loadings.

func (*Module) SetGuard added in v0.1.0 

func (m *Module) SetGuard(g RequestGuard)

SetGuard sets the request guard for this module, useful for setting custom guards for testing or multiple loadings.

func (*Module) StringDict 

func (m *Module) StringDict() starlark.StringDict

StringDict returns all module methods in a starlark.StringDict

func (*Module) Struct 

func (m *Module) Struct() *starlarkstruct.Struct

Struct returns this module's supported methods as a starlark Struct

type RequestGuard 

type RequestGuard interface {
	Allowed(thread *starlark.Thread, req *http.Request) (*http.Request, error)
}

RequestGuard controls access to http by checking before making requests if Allowed returns an error the request will be denied

type Response 

type Response struct {
	http.Response
}

Response represents an HTTP response, wrapping a Go http.Response with Starlark methods.

func (*Response) HeadersDict 

func (r *Response) HeadersDict() *starlark.Dict

HeadersDict flops

func (*Response) JSON 

func (r *Response) JSON(thread *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

JSON attempts to parse the response body as JSON

func (*Response) Struct 

func (r *Response) Struct() *starlarkstruct.Struct

Struct turns a response into a *starlark.Struct

func (*Response) Text 

func (r *Response) Text(thread *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

Text returns the raw data as a string

type ServerResponse added in v0.0.11 

type ServerResponse struct {
	// contains filtered or unexported fields
}

ServerResponse is a struct that enables HTTP response manipulation within Starlark scripts, facilitating dynamic preparation of HTTP responses in Go-based web servers executing such scripts.

Key Features:

  • Setting HTTP status codes.
  • Adding and managing HTTP headers.
  • Specifying the content type of the response.
  • Setting the response body with support for various data types (e.g., binary, text, HTML, JSON).

Usage Pattern:

  1. Create a ServerResponse instance using NewServerResponse().
  2. Utilize the Struct() method to obtain a Starlark struct that exposes ServerResponse functionalities to Starlark scripts.
  3. In the Starlark script, utilize provided methods (e.g., set_status, add_header, set_content_type) to prepare the response.
  4. Back in Go, the ServerResponse instance can directly write its content to an http.ResponseWriter using its Write() method. Alternatively, you can call the Export() method to convert the ServerResponse into an ExportedServerResponse for modification, which is then capable of being written to an http.ResponseWriter using its Write() method.

Internally, ServerResponse uses a private contentDataType enum to manage the intended type of the response data, allowing for automatic adjustment of the Content-Type header based on the set data type by the Starlark script.

The ExportedServerResponse struct simplifies ServerResponse for interoperability with Go's standard http package, comprising an HTTP status code, headers, and data for the HTTP response. Its Write() method allows for the prepared response to be efficiently written to an http.ResponseWriter, ensuring correct header setting and response body data writing.

Note: Direct manipulation of ServerResponse and its methods by Starlark scripts necessitates validation of script inputs to mitigate potential security issues like header injection attacks. This design allows scripts to dynamically prepare HTTP responses while maintaining a secure and controlled server environment.

func NewServerResponse added in v0.0.11 

func NewServerResponse() *ServerResponse

NewServerResponse creates a new ServerResponse.

func (*ServerResponse) Export added in v0.0.11 

func (r *ServerResponse) Export() *ExportedServerResponse

Export dumps the response data to a struct for later use in Go.

func (*ServerResponse) Struct added in v0.0.11 

func (r *ServerResponse) Struct() *starlarkstruct.Struct

Struct returns a Starlark struct representation of the ServerResponse, which exposes the following methods to Starlark scripts:

  • set_status(code): Sets the HTTP status code for the response.
  • set_code(code): An alias for set_status.
  • add_header(key, value): Adds a header with the given key and value to the response.
  • set_content_type(contentType): Sets the Content-Type header for the response.
  • set_data(data): Sets the response data as binary data.
  • set_json(data): Sets the response data as JSON, marshaling the given Starlark value to JSON.
  • set_text(data): Sets the response data as plain text.
  • set_html(data): Sets the response data as HTML.

func (*ServerResponse) Write added in v0.0.11 

func (r *ServerResponse) Write(w http.ResponseWriter) (err error)

Write writes the response to http.ResponseWriter.

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.