client

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 New(baseURL string, tlsConfig *tls.Config) (*Client, error)
  • 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

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

func New(baseURL string, tlsConfig *tls.Config) (*Client, error)

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

func (c *Client) CreateInvoice(inv types.Invoice) (*types.InvoiceCreateResponse, error)

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

func (c *Client) CreateParcel(bindleID string, sha string, data []byte) error

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

func (c *Client) CreateParcelFromFile(bindleID string, sha string, path string) error

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

func (c *Client) CreateParcelFromReader(bindleID string, sha string, data io.ReadCloser) error

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

func (c *Client) GetInvoice(id string) (*types.Invoice, error)

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

func (c *Client) GetParcel(bindleID string, sha string) ([]byte, error)

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

func (c *Client) GetParcelReader(bindleID string, sha string) (io.ReadCloser, error)

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

func (c *Client) GetYankedInvoice(id string) (*types.Invoice, error)

GetYankedInvoice is the same as `GetInvoice`, but allows you to return an invoice that has been yanked

func (*Client) QueryInvoices

func (c *Client) QueryInvoices(opts types.QueryOptions) (*types.Matches, error)

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

func (c *Client) YankInvoice(id string) error

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