web

Documentation

Overview

Package web provides high-level functions that are called from the Go Bonzai branch of the same name providing universal access to the core functionality.

Index

• Variables
• type HTTPError
  • func (e HTTPError) Error() string
• type Head
• type Req
  • func (req *Req) Submit() error
• type ReqSyntaxError
  • func (e ReqSyntaxError) Error() string

Variables

var Client = http.DefaultClient

Client provides a way to change the default HTTP client for any further package HTTP request function calls. The Client can also be set in any Req by assigning the to the field of the same name. By default, it is set to http.DefaultClient. This is particularly useful when creating mockups and other testing.

var TimeOut int = 60

TimeOut is a package global timeout for any of the high-level https query functions in this package. The default value is 60 seconds.

Types

type HTTPError

type HTTPError struct {
	Resp *http.Response
}

HTTPError is an error for anything other than an HTTP response in the 200-299 range including the 300 redirects (which should be handled by the Req.Submit successfully before returning). http.Response is embedded directly for details.

func (HTTPError) Error

func (e HTTPError) Error() string

Error fulfills the error interface.

type Head

type Head map[string]string

Head contains headers to be added to a Req. Unlike the specification, only one header of a give name is allowed. For more precision the net/http library directly should be used instead.

type Req

type Req struct {
	U string          // base url, optional query string
	D any             // data to be populated and/or overwritten
	M string          // all caps method (default: GET)
	Q url.Values      // query string to append to URL (if none already)
	H Head            // header map, never more than one of same
	B any             // body data, url.Values will x-www-form-urlencoded
	C context.Context // trigger requests with context
	R *http.Response  // actual http.Response
}

Req is a human-friendly way to think of web requests. This design is closer a pragmatic curl requests than the canonical specification (unique headers, for example). The type and parameters of the web request and response are derived from the Req fields. The single-letter struct fields are terse but convenient. Use net/http when more precision is required.

The body (B) can be one of several types that till trigger what is submitted as data portion of the request:

url.Values - triggers x-www-form-urlencoded
byte       - uuencoded binary data
string     - plain text

Note that Req has no support for multi-part MIME. Use net/http directly if such is required.

The data (D) field can also be any of several types that trigger how the received data is handled:

[]byte           - uudecoded binary
string           - plain text string
io.Writer        - keep as is
json.This        - unmarshaled JSON data into This
any              - unmarshaled JSON data

Passing the query string as url.Values automatically add a question mark (?) followed by the URL encoded values to the end of the URL which may present a problem if the URL already has a query string. Encouraging the use of url.Values for passing the query string serves as a reminder that all query strings should be URL encoded (as is often forgotten).

func (*Req) Submit

func (req *Req) Submit() error

Submit synchronously sends the Req to server and populates the response from the server into D. Anything but a response in the 200s will result in an HTTPError. See Req for details on how inspection of Req will change the behavior of Submit automatically. It Req.C is nil a context.WithTimeout will be used and with the value of web.TimeOut.

type ReqSyntaxError

type ReqSyntaxError struct {
	Message string
}

ReqSyntaxError is for any error involving the incorrect definition of Req fields (such as including a question mark in the URL, etc.).

func (ReqSyntaxError) Error

func (e ReqSyntaxError) Error() string

Error fulfills the error interface.