Documentation
¶
Overview ¶
Package client is a fully featured client for talking to a Bindle server. Underneath the hood, Bindle uses HTTP/2 for communicating with the Bindle server. This enables a consumer to make multiple parallel requests for parcels using the same underlying connection
Bindle IDs and SHAs ¶
Many of the client functions take `bindleID` and `sha` parameters. Bindle IDs are arbitrarily pathy names (e.g. example.com/foo/bar) plus a strict semver version (e.g. 1.0.0), resulting in an ID of "example.com/foo/bar/1.0.0". The sha parameter is a SHA256 sum of a given parcel and should match the SHA of the data you are sending, otherwise it will be rejected
Index ¶
- type Client
- func (c *Client) CreateInvoice(inv types.Invoice) (*types.InvoiceCreateResponse, error)
- func (c *Client) CreateInvoiceFromFile(path string) (*types.InvoiceCreateResponse, error)
- func (c *Client) CreateParcel(bindleID string, sha string, data []byte) error
- func (c *Client) CreateParcelFromFile(bindleID string, sha string, path string) error
- func (c *Client) CreateParcelFromReader(bindleID string, sha string, data io.ReadCloser) error
- func (c *Client) GetInvoice(id string) (*types.Invoice, error)
- func (c *Client) GetMissingParcels(id string) (*types.MissingParcelsResponse, error)
- func (c *Client) GetParcel(bindleID string, sha string) ([]byte, error)
- func (c *Client) GetParcelReader(bindleID string, sha string) (io.ReadCloser, error)
- func (c *Client) GetYankedInvoice(id string) (*types.Invoice, error)
- func (c *Client) QueryInvoices(opts types.QueryOptions) (*types.Matches, error)
- func (c *Client) RawRequest(path string, method string, data io.ReadCloser, contentType string) (*http.Response, error)
- func (c *Client) YankInvoice(id string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the struct that contains all necessary information for communicating with a Bindle Server
func New ¶
New returns a new Client configured to use the given baseURL. This URL should be the entire base part of your Bindle server. So if your Bindle server is namespaced (with something like v1), then the baseURL should contain that part of the URL (e.g. https://bindle.example.com/v1 instead of https://bindle.example.com). The tlsConfig parameter is optional and can be used if you have any specific TLS configuration options such as internally signed certificates
func (*Client) CreateInvoice ¶
CreateInvoice from the given `Invoice` object. Returns a response containing the newly created invoice and a list of any missing parcels that need to be uploaded
func (*Client) CreateInvoiceFromFile ¶
func (c *Client) CreateInvoiceFromFile(path string) (*types.InvoiceCreateResponse, error)
CreateInvoiceFromFile is the same as `CreateInvoice`, but instead takes a path to an invoice TOML file to send to the server
func (*Client) CreateParcel ¶
CreateParcel uploads a parcel for the given `bindleID`. The `sha` value must match the SHA256 sum of the data or the server will reject the parcel. This function takes the parcel data as a raw byte array. For larger parcels, it is recommended to use `CreateParcelFromFile` or `CreateParcelFromReader` to avoid loading them into memory.
Please note that for best efficiency, consumers should only upload parcels that do not already exist as indicated by the server (either in the `InvoiceCreateResponse` or by using the `GetMissingParcels` function)
func (*Client) CreateParcelFromFile ¶
CreateParcelFromFile is the same as `CreateParcel` but takes a path to a file to upload for a parcel. This file will be streamed to the server and not loaded into memory
func (*Client) CreateParcelFromReader ¶
CreateParcelFromReader is the same as `CreateParcel` but takes anything that is a `ReadCloser` to use for the parcel. This function will stream the data from the reader to the server and then close the reader
func (*Client) GetInvoice ¶
GetInvoice returns an `Invoice` with the given ID. This will return an error if the invoice is yanked
func (*Client) GetMissingParcels ¶
func (c *Client) GetMissingParcels(id string) (*types.MissingParcelsResponse, error)
GetMissingParcels checks with the server if there are any missing parcels for the given Bindle ID. Returns a response containing the list of missing parcels, if any
func (*Client) GetParcel ¶
GetParcel returns the parcel identified by the Bindle ID and parcel SHA. This loads the data into memory as a byte array and is not recommended for use with larger parcels. For larger parcels (or when writing directly to another source), use the `GetParcelReader` function instead
func (*Client) GetParcelReader ¶
GetParcelReader is similar to `GetParcel` but returns the parcel as a reader (for streaming purposes). This will be more efficient for larger files
func (*Client) GetYankedInvoice ¶
GetYankedInvoice is the same as `GetInvoice`, but allows you to return an invoice that has been yanked
func (*Client) QueryInvoices ¶
QueryInvoices allows you to search and filter invoices from the Bindle server. Bindle servers are allowed to implement their query engines differently, so the number of matches may vary depending on the server, particularly in their use of `strict` mode. Returns a `Matches` object containing information about the query, pagination data, and the list of responses
func (*Client) RawRequest ¶
func (c *Client) RawRequest(path string, method string, data io.ReadCloser, contentType string) (*http.Response, error)
RawRequests performs an HTTP request using the underlying HTTP client and base URL. The given path is appended to the URL and the data body is optional. If a body is specified, the contentType can be specified as well, otherwise contentType will be ignored
func (*Client) YankInvoice ¶
YankInvoice allows you to "yank," or mark as no longer available, an invoice of the given ID. Invoices cannot be deleted from a Bindle server, so this notifies users that it should not be consumed
Source Files