Documentation
¶
Overview ¶
The httpbakery package layers on top of the bakery package - it provides an HTTP-based implementation of a macaroon client and server.
Index ¶
- Constants
- Variables
- func Do(client *http.Client, req *http.Request, visitWebPage func(url *url.URL) error, ...) (*http.Response, error)
- func WriteDischargeRequiredError(w http.ResponseWriter, m *macaroon.Macaroon, originalErr error)
- type Error
- type ErrorCode
- type ErrorInfo
- type Service
- type WaitResponse
Constants ¶
const ( ErrBadRequest = ErrorCode("bad request") ErrDischargeRequired = ErrorCode("macaroon discharge required") ErrInteractionRequired = ErrorCode("interaction required") )
Variables ¶
var DefaultHTTPClient = defaultHTTPClient()
DefaultHTTPClient is an http.Client that ensures that headers are sent to the server even when the server redirects.
Functions ¶
func Do ¶
func Do(client *http.Client, req *http.Request, visitWebPage func(url *url.URL) error, getBody func() io.ReadCloser) (*http.Response, error)
Do makes an http request to the given client. If the request fails with a discharge-required error, any required discharge macaroons will be acquired, and the request will be repeated with those attached.
If the client.Jar field is non-nil, the macaroons will be stored there and made available to subsequent requests.
func WriteDischargeRequiredError ¶
func WriteDischargeRequiredError(w http.ResponseWriter, m *macaroon.Macaroon, originalErr error)
WriteDischargeRequiredError writes a response to w that reports the given error and sends the given macaroon to the client, indicating that it should be discharged to allow the original request to be accepted.
Types ¶
type Error ¶
type Error struct {
Code ErrorCode `json:",omitempty"`
Message string `json:",omitempty"`
Info *ErrorInfo `json:",omitempty"`
}
Error holds the type of a response from an httpbakery HTTP request, marshaled as JSON.
type ErrorCode ¶
type ErrorCode string
ErrorCode holds an error code that classifies an error returned from a bakery HTTP handler.
type ErrorInfo ¶
type ErrorInfo struct {
// Macaroon may hold a macaroon that, when
// discharged, may allow access to a service.
// This field is associated with the ErrDischargeRequired
// error code.
Macaroon *macaroon.Macaroon `json:",omitempty"`
// VisitURL holds a URL that the client should visit
// in a web browser to authenticate themselves.
VisitURL string `json:",omitempty"`
// WaitURL holds a URL that the client should visit
// to acquire the discharge macaroon. A GET on
// this URL will block until the client has authenticated,
// and then it will return the discharge macaroon.
WaitURL string `json:",omitempty"`
}
ErrorInfo holds additional information provided by an error.
type Service ¶
Service represents a service that can use client-provided macaroons to authorize requests. It layers on top of *bakery.Service, providing http-based methods to create third-party caveats.
func NewService ¶
func NewService(p bakery.NewServiceParams) (*Service, error)
NewService returns a new Service.
func (*Service) AddDischargeHandler ¶
func (svc *Service) AddDischargeHandler( rootPath string, mux *http.ServeMux, checker func(req *http.Request, cavId, cav string) ([]bakery.Caveat, error), )
AddDischargeHandler handles adds handlers to the given ServeMux under the given root path to service third party caveats. If rootPath is empty, "/" will be used.
The check function is used to check whether a client making the given request should be allowed a discharge for the given caveat. If it does not return an error, the caveat will be discharged, with any returned caveats also added to the discharge macaroon. If it returns an error with a *Error cause, the error will be marshaled and sent back to the client.
The name space served by DischargeHandler is as follows. All parameters can be provided either as URL attributes or form attributes. The result is always formatted as a JSON object.
On failure, all endpoints return an error described by the Error type.
POST /discharge
params:
id: id of macaroon to discharge
location: location of original macaroon (optional (?))
?? flow=redirect|newwindow
result on success (http.StatusOK):
{
Macaroon *macaroon.Macaroon
}
POST /create
params:
condition: caveat condition to discharge
rootkey: root key of discharge caveat
result:
{
CaveatID: string
}
GET /publickey
result: public key of service expiry time of key
func (*Service) NewRequest ¶
func (svc *Service) NewRequest(httpReq *http.Request, checker bakery.FirstPartyChecker) *bakery.Request
NewRequest returns a new request, converting cookies from the HTTP request into macaroons in the bakery request when they're found. Mmm.
type WaitResponse ¶
type WaitResponse struct {
Macaroon *macaroon.Macaroon
}
WaitResponse holds the type that should be returned by an HTTP response made to a WaitURL (See the ErrorInfo type).
Source Files