client

package
v1.4.30-prerelease Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2024 License: Apache-2.0 Imports: 21 Imported by: 13

Documentation

Overview

Package client provides API client methods that interact with our API to manage Border0 resources.

Example to create a new client: 

api := client.New(
	client.WithAuthToken(os.Getenv("BORDER0_AUTH_TOKEN")), // optional, if not provided, Border0 SDK will use BORDER0_AUTH_TOKEN env var
	client.WithRetryMax(2),                                // 1 initial + 2 retries = 3 attempts
)

See Option for more configurable options.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExponentialBackoff 

func ExponentialBackoff(min, max time.Duration, attempt int) time.Duration

ExponentialBackoff is a Backoff function which will backoff exponentially between the given minimum and maximum durations. The attempt number is used as the exponent base, so the first attempt will backoff by the minimum duration, the second attempt will backoff by twice the minimum duration, the third attempt will backoff by four times the minimum duration, and so on. The maximum duration is used as a cap, so the backoff will never exceed the maximum duration.

func NotFound added in v0.1.22 

func NotFound(err error) bool

Types

type APIClient 

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

APIClient is the client for the Border0 API.

func New 

func New(options ...Option) *APIClient

New creates a new Border0 API client.

func (*APIClient) AttachPoliciesToSocket added in v1.3.0 

func (api *APIClient) AttachPoliciesToSocket(ctx context.Context, policyIDs []string, socketID string) (err error)

AttachPoliciesToSocket attaches multiple policies to a socket by policy IDs and socket ID.

func (*APIClient) AttachPolicyToSocket added in v1.1.0 

func (api *APIClient) AttachPolicyToSocket(ctx context.Context, policyID string, socketID string) (err error)

AttachPolicyToSocket attaches a policy to a socket by policy ID and socket ID.

func (*APIClient) Authenticate added in v1.4.30 

func (api *APIClient) Authenticate(ctx context.Context, opts ...auth.Option) error

Authenticate authenticates the client.

func (*APIClient) Connector added in v1.0.0 

func (api *APIClient) Connector(ctx context.Context, id string) (out *Connector, err error)

Connector fetches a connector from your Border0 organization by UUID. Connector UUID is globally unique and immutable.

func (*APIClient) ConnectorToken added in v1.4.18 

func (api *APIClient) ConnectorToken(ctx context.Context, connectorID string, tokenID string) (out *ConnectorToken, err error)

ConnectorToken fetches a connector's token by connector UUID and token UUID.

func (*APIClient) ConnectorTokens added in v1.0.0 

func (api *APIClient) ConnectorTokens(ctx context.Context, connectorID string) (out *ConnectorTokens, err error)

ConnectorTokens fetches all tokens for a connector by connector's UUID.

func (*APIClient) Connectors added in v1.0.0 

func (api *APIClient) Connectors(ctx context.Context) (out []Connector, err error)

Connectors fetches all connectors in your Border0 organization.

func (*APIClient) CreateConnector added in v1.0.0 

func (api *APIClient) CreateConnector(ctx context.Context, in *Connector) (out *Connector, err error)

CreateConnector creates a new connector in your Border0 organization. Connector name must be unique within your organization, otherwise API will return an error. Connector name must contain only lowercase letters, numbers and dashes.

func (*APIClient) CreateConnectorToken added in v1.0.0 

func (api *APIClient) CreateConnectorToken(ctx context.Context, in *ConnectorToken) (out *ConnectorToken, err error)

CreateConnectorToken creates a new token for a connector. Token is used to authenticate connector with Border0 API. Token can be created with or without a expiration date. If ExpiresAt field is not set, token will not expire.

func (*APIClient) CreatePolicy added in v1.1.0 

func (api *APIClient) CreatePolicy(ctx context.Context, in *Policy) (out *Policy, err error)

CreatePolicy creates a new policy in your Border0 organization. Policy name must be unique within your organization, otherwise API will return an error. Policy name must contain only lowercase letters, numbers and dashes.

func (*APIClient) CreateSocket 

func (api *APIClient) CreateSocket(ctx context.Context, in *Socket) (out *Socket, err error)

CreateSocket creates a new socket in your Border0 organization. Socket name must be unique within your organization, otherwise, an error will be returned. Socket type is required and must be one of the following: "http", "ssh", "tls" or "database". Socket name name must contain only lowercase letters, numbers and dashes.

func (*APIClient) DeleteConnector added in v1.0.0 

func (api *APIClient) DeleteConnector(ctx context.Context, id string) (err error)

DeleteConnector deletes a connector from your Border0 organization by connector's UUID.

func (*APIClient) DeleteConnectorToken added in v1.0.0 

func (api *APIClient) DeleteConnectorToken(ctx context.Context, connectorID, tokenID string) (err error)

DeleteConnectorToken deletes a token for a connector by connector's UUID and token's UUID.

func (*APIClient) DeletePolicy added in v1.1.0 

func (api *APIClient) DeletePolicy(ctx context.Context, id string) (err error)

DeletePolicy deletes a policy from your Border0 organization by policy ID.

func (*APIClient) DeleteSocket added in v0.1.22 

func (api *APIClient) DeleteSocket(ctx context.Context, idOrName string) (err error)

DeleteSocket deletes a socket in your Border0 organization. If the socket does not exist, no error will be returned.

func (*APIClient) Policies added in v1.1.0 

func (api *APIClient) Policies(ctx context.Context) (out []Policy, err error)

Policies fetches all policies in your Border0 organization.

func (*APIClient) PoliciesByNames added in v1.3.0 

func (api *APIClient) PoliciesByNames(ctx context.Context, names ...string) (out []Policy, err error)

PoliciesByNames finds policies in your Border0 organization by policy names. If any of the policies does not exist, an error will be returned. When only one policy name is provided, this method will use the /policies/find endpoint, otherwise it will fetch all policies and filter them by name.

func (*APIClient) Policy added in v1.1.0 

func (api *APIClient) Policy(ctx context.Context, id string) (out *Policy, err error)

Policy fetches a policy from your Border0 organization by policy ID.

func (*APIClient) RemovePoliciesFromSocket added in v1.3.0 

func (api *APIClient) RemovePoliciesFromSocket(ctx context.Context, policyIDs []string, socketID string) (err error)

RemovePoliciesFromSocket detaches multiple policies from a socket by policy IDs and socket ID.

func (*APIClient) RemovePolicyFromSocket added in v1.1.0 

func (api *APIClient) RemovePolicyFromSocket(ctx context.Context, policyID string, socketID string) (err error)

RemovePolicyFromSocket detaches a policy from a socket with policy ID and socket ID.

func (*APIClient) SignSocketKey 

func (api *APIClient) SignSocketKey(ctx context.Context, idOrName string, in *SocketKeyToSign) (out *SignedSocketKey, err error)

SignSocketKey generates a signed SSH certificate for a socket. The SSH public key must be in OpenSSH format. The SSH certificate will be valid for 5 minutes. The host key is the public key Border0 server. It can be used to verify the SSH certificate.

func (*APIClient) Socket 

func (api *APIClient) Socket(ctx context.Context, idOrName string) (out *Socket, err error)

Socket fetches a socket by socket UUID or name. Socket UUID is globally unique and socket name is unique within a Border0 organization.

func (*APIClient) SocketConnectors added in v1.0.0 

func (api *APIClient) SocketConnectors(ctx context.Context, idOrName string) (out *SocketConnectors, err error)

SocketConnectors fetches all connectors that are linked to a socket.

func (*APIClient) SocketUpstreamConfigs added in v1.0.0 

func (api *APIClient) SocketUpstreamConfigs(ctx context.Context, idOrName string) (out *SocketUpstreamConfigs, err error)

SocketUpstreamConfigs fetches all upstream configurations for a socket.

func (*APIClient) Sockets added in v0.1.22 

func (api *APIClient) Sockets(ctx context.Context) (out []Socket, err error)

Sockets fetches all sockets in your Border0 organization.

func (*APIClient) TokenClaims 

func (api *APIClient) TokenClaims() (jwt.MapClaims, error)

TokenClaims returns the claims of the JWT token.

func (*APIClient) UpdateConnector added in v1.0.0 

func (api *APIClient) UpdateConnector(ctx context.Context, in *Connector) (out *Connector, err error)

UpdateConnector updates an existing connector in your Border0 organization.

func (*APIClient) UpdatePolicy added in v1.1.0 

func (api *APIClient) UpdatePolicy(ctx context.Context, id string, in *Policy) (out *Policy, err error)

UpdatePolicy updates an existing policy in your Border0 organization.

func (*APIClient) UpdateSocket added in v0.1.22 

func (api *APIClient) UpdateSocket(ctx context.Context, idOrName string, in *Socket) (out *Socket, err error)

UpdateSocket updates an existing socket in your Border0 organization.

type AuthenticationService added in v1.4.30 

type AuthenticationService interface {
	// TODO: IsAuthenticated(ctx context.Context) (bool, error)
	Authenticate(ctx context.Context, opts ...auth.Option) error
}

AuthenticationService is an interface for API client methods that interact with Border0 API to manage authentication.

type Backoff 

type Backoff func(min, max time.Duration, attempt int) time.Duration

Backoff is a callback function which will be called by APIClient when performing retries. It is passed the minimum and maximum durations to backoff between, as well as the attempt number (starting at zero)

type Connector added in v1.0.0 

type Connector struct {
	// input and output fields
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// output field
	ConnectorID string `json:"connector_id"`

	// built-in SSH service
	BuiltInSshServiceEnabled bool    `json:"built_in_ssh_service_enabled,omitempty"`
	BuiltInSshService        *Socket `json:"built_in_ssh_service,omitempty"` // optional, nil if built-in SSH service is disabled
}

Connector represents a connector in your Border0 organization.

type ConnectorService added in v1.0.0 

type ConnectorService interface {
	Connector(ctx context.Context, id string) (out *Connector, err error)
	Connectors(ctx context.Context) (out []Connector, err error)
	CreateConnector(ctx context.Context, in *Connector) (out *Connector, err error)
	UpdateConnector(ctx context.Context, in *Connector) (out *Connector, err error)
	DeleteConnector(ctx context.Context, id string) (err error)
	ConnectorTokens(ctx context.Context, connectorID string) (out *ConnectorTokens, err error)
	ConnectorToken(ctx context.Context, connectorID string, tokenID string) (out *ConnectorToken, err error)
	CreateConnectorToken(ctx context.Context, in *ConnectorToken) (out *ConnectorToken, err error)
	DeleteConnectorToken(ctx context.Context, connectorID, tokenID string) (err error)
}

ConnectorService is an interface for API client methods that interact with Border0 API to manage connectors and connector tokens.

type ConnectorToken added in v1.0.0 

type ConnectorToken struct {
	// input and output fields
	ConnectorID string       `json:"connector_id"`
	Name        string       `json:"name"`
	ExpiresAt   FlexibleTime `json:"expires_at,omitempty"`

	// additional output fields
	ID        string       `json:"id"`
	Token     string       `json:"token"`
	CreatedBy string       `json:"created_by"`
	CreatedAt FlexibleTime `json:"created_at"`
}

ConnectorToken represents a token for a connector.

type ConnectorTokens added in v1.0.0 

type ConnectorTokens struct {
	List      []ConnectorToken `json:"list"`
	Connector Connector        `json:"connector"`
}

ConnectorTokens represents a list of tokens for a connector.

type Error 

type Error struct {
	Code     int    `json:"status_code"`
	Message  string `json:"error_message"`
	Fallback string `json:"message"`
}

Error is an error returned by the API server.

func APIErrorFrom 

func APIErrorFrom(resp *http.Response) Error

APIErrorFrom creates an Error from an HTTP response.

func (Error) Error 

func (e Error) Error() string

Error returns string representation of an Error.

type FlexibleTime added in v1.0.0 

type FlexibleTime struct {
	time.Time
}

FlexibleTime is a time.Time that can be unmarshalled from either a string (RFC3339) or a number (unix timestamp). On marshalling, it is always marshalled as a number (unix timestamp). FlexibleTime is used for Border0 API connector token's `expires_at` and `created_at` fields.

func FlexibleTimeFrom added in v1.0.0 

func FlexibleTimeFrom(s string) (FlexibleTime, error)

FlexibleTimeFrom returns a new FlexibleTime set to the given time from a string in RFC3339 format. It's a helper function for FlexibleTime.

func (FlexibleTime) MarshalJSON added in v1.0.0 

func (f FlexibleTime) MarshalJSON() ([]byte, error)

MarshalJSON marshals the FlexibleTime as a unix timestamp.

func (FlexibleTime) String added in v1.0.0 

func (f FlexibleTime) String() string

String returns the FlexibleTime as a string in RFC3339 format. If the FlexibleTime is zero, it returns an empty string.

func (*FlexibleTime) UnmarshalJSON added in v1.0.0 

func (f *FlexibleTime) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the FlexibleTime from either a string (RFC3339) or a number (unix timestamp).

type HTTPClient 

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

HTTPClient is a wrapper around http.Client that handles authentication, request/response encoding/decoding, and error handling.

func (*HTTPClient) Close 

func (h *HTTPClient) Close()

Close closes idle connections in the underlying HTTP client.

func (*HTTPClient) Request 

func (h *HTTPClient) Request(ctx context.Context, method, path string, input, output any, edits ...reqedit.EditRequestFunc) (int, error)

Request sends an HTTP request to the API server.

type HTTPRequester 

type HTTPRequester interface {
	Request(ctx context.Context, method, path string, input, output any, edits ...reqedit.EditRequestFunc) (int, error)
	Close()
}

HTTPRequester is an interface for HTTPClient.

type Option 

type Option func(*APIClient)

Option is a function that can be passed to NewAPIClient to configure it.

func WithAuthToken 

func WithAuthToken(token string) Option

WithAuthToken sets the auth token for Border0 api calls.

func WithBackoff 

func WithBackoff(fn Backoff) Option

WithBackoff sets the backoff function that's used to calculate the wait time between retries of failed api calls.

func WithBaseURL 

func WithBaseURL(url string) Option

WithBaseURL sets the base url for Border0 api calls.

func WithRetryMax 

func WithRetryMax(attempts int) Option

WithRetryMax sets the maximum number of retries of failed api calls.

func WithRetryWaitMax 

func WithRetryWaitMax(wait time.Duration) Option

WithRetryWaitMax sets the maximum wait time between retries of failed api calls.

func WithRetryWaitMin 

func WithRetryWaitMin(wait time.Duration) Option

WithRetryWaitMin sets the minimum wait time between retries of failed api calls.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the timeout for the underlying http client.

type Policy added in v1.1.0 

type Policy struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Description string     `json:"description"`
	OrgID       string     `json:"org_id"`
	OrgWide     bool       `json:"org_wide"`
	PolicyData  PolicyData `json:"policy_data"`
	CreatedAt   time.Time  `json:"created_at"`
	SocketIDs   []string   `json:"socket_ids"`
	Deleted     bool       `json:"deleted"`
}

Policy represents a Border0 policy in your organization. See PolicyData for more details about the policy data schema. A policy can be set to be organization-wide, in which case it will be applied to all sockets in your organization. If a policy is not organization-wide, it can be attached to individual sockets. See [AttachPolicyToSocket] and [RemovePolicyFromSocket] for more details.

type PolicyCondition added in v1.1.0 

type PolicyCondition struct {
	Who   PolicyWho   `json:"who,omitempty"`
	Where PolicyWhere `json:"where,omitempty"`
	When  PolicyWhen  `json:"when,omitempty"`
}

PolicyCondition represents the policy condition schema. A policy condition can define "who", "where" and "when" conditions. See PolicyWho, PolicyWhere and PolicyWhen for more details about the policy condition schema.

type PolicyData added in v1.1.0 

type PolicyData struct {
	Version   string          `json:"version"`
	Action    []string        `json:"action"`
	Condition PolicyCondition `json:"condition"`
}

PolicyData represents the policy data schema. A policy can have multiple actions, and its condition determines when the actions are applied. See PolicyCondition for more details about the policy condition schema.

type PolicyService added in v1.1.0 

type PolicyService interface {
	Policy(ctx context.Context, id string) (out *Policy, err error)
	Policies(ctx context.Context) (out []Policy, err error)
	PoliciesByNames(ctx context.Context, names ...string) (out []Policy, err error)
	CreatePolicy(ctx context.Context, in *Policy) (out *Policy, err error)
	UpdatePolicy(ctx context.Context, id string, in *Policy) (out *Policy, err error)
	DeletePolicy(ctx context.Context, id string) (err error)
	AttachPolicyToSocket(ctx context.Context, policyID string, socketID string) (err error)
	RemovePolicyFromSocket(ctx context.Context, policyID string, socketID string) (err error)
	AttachPoliciesToSocket(ctx context.Context, policyIDs []string, socketID string) (err error)
	RemovePoliciesFromSocket(ctx context.Context, policyIDs []string, socketID string) (err error)
}

PolicyService is an interface for API client methods that interact with Border0 API to manage policies and policy socket attachments.

type PolicySocketAttachment added in v1.1.0 

type PolicySocketAttachment struct {
	Action string `json:"action" binding:"required"`
	ID     string `json:"id" binding:"required"`
}

PolicySocketAttachment represents a single policy socket attachment. The action can be "add" or "remove", and the ID is the socket ID.

type PolicySocketAttachments added in v1.1.0 

type PolicySocketAttachments struct {
	Actions []PolicySocketAttachment `json:"actions"`
}

PolicySocketAttachments represents a list of policy socket attachments. Border0 API client uses this schema to attach or detach a policy to/from a socket.

type PolicyWhen added in v1.1.0 

type PolicyWhen struct {
	After           string `json:"after,omitempty"`
	Before          string `json:"before,omitempty"`
	TimeOfDayAfter  string `json:"time_of_day_after,omitempty"`
	TimeOfDayBefore string `json:"time_of_day_before,omitempty"`
}

PolicyWhen represents the policy condition "when" schema. It specifies when the policy applies to, based on allowed dates and allowed times of day.

type PolicyWhere added in v1.1.0 

type PolicyWhere struct {
	AllowedIP  []string `json:"allowed_ip,omitempty"`
	Country    []string `json:"country,omitempty"`
	CountryNot []string `json:"country_not,omitempty"`
}

PolicyWhere represents the policy condition "where" schema. It specifies where the policy applies to, based on allowed IP addresses, allowed countries and countries not allowed.

type PolicyWho added in v1.1.0 

type PolicyWho struct {
	Email  []string `json:"email,omitempty"`
	Domain []string `json:"domain,omitempty"`
	Group  []string `json:"group,omitempty"`
}

PolicyWho represents the policy condition "who" schema. It specifies who the policy applies to, based on allowed email addresses and allowed email domains.

type Requester 

type Requester interface {
	TokenClaims() (jwt.MapClaims, error)
	SocketService
	ConnectorService
	PolicyService
}

Requester is the interface for the Border0 API client.

type SignedSocketKey 

type SignedSocketKey struct {
	SignedSSHCert string `json:"signed_ssh_cert"`
	HostKey       string `json:"host_key"`
}

SignedSocketKey represents a signed SSH certificate and the host key.

type Socket 

type Socket struct {
	Name                 string            `json:"name"`
	SocketID             string            `json:"socket_id"`
	SocketType           string            `json:"socket_type"`
	Description          string            `json:"description,omitempty"`
	UpstreamType         string            `json:"upstream_type,omitempty"`
	UpstreamHTTPHostname string            `json:"upstream_http_hostname,omitempty"`
	RecordingEnabled     bool              `json:"recording_enabled"`
	Tags                 map[string]string `json:"tags,omitempty"`

	// link to a connector with upstream config
	ConnectorID    string                 `json:"connector_id,omitempty"`
	UpstreamConfig *service.Configuration `json:"upstream_configuration,omitempty"`

	// associated policies
	Policies []Policy `json:"policies,omitempty"`

	// output fields
	DNS string `json:"dnsname,omitempty"`
}

Socket represents a socket in Border0 API. A socket can be linked to a connector with upstream configuration. Use `ConnectorID` to link a socket to a connector, and use `UpstreamConfig` to configure upstream for a socket.

type SocketConnector added in v1.0.0 

type SocketConnector struct {
	ID            uint64 `json:"id"`
	ConnectorID   string `json:"connector_id"`
	ConnectorName string `json:"connector_name"`
	SocketID      string `json:"socket_id"`
	CreatedAt     string `json:"created_at"`
	UpdatedAt     string `json:"updated_at"`
}

SocketConnector represents a connector that is linked to a socket.

type SocketConnectors added in v1.0.0 

type SocketConnectors struct {
	List []SocketConnector `json:"list"`
}

SocketConnectors represents a list of connectors that are linked to a socket.

type SocketKeyToSign 

type SocketKeyToSign struct {
	SSHPublicKey string `json:"ssh_public_key"`
}

SocketKeyToSign represents a SSH public key to sign.

type SocketService 

type SocketService interface {
	Socket(ctx context.Context, idOrName string) (out *Socket, err error)
	Sockets(ctx context.Context) (out []Socket, err error)
	CreateSocket(ctx context.Context, in *Socket) (out *Socket, err error)
	UpdateSocket(ctx context.Context, idOrName string, in *Socket) (out *Socket, err error)
	DeleteSocket(ctx context.Context, idOrName string) (err error)
	SocketConnectors(ctx context.Context, idOrName string) (out *SocketConnectors, err error)
	SocketUpstreamConfigs(ctx context.Context, idOrName string) (out *SocketUpstreamConfigs, err error)
	SignSocketKey(ctx context.Context, idOrName string, in *SocketKeyToSign) (out *SignedSocketKey, err error)
}

SocketService is an interface for API client methods that interact with Border0 API to manage sockets.

type SocketUpstreamConfig added in v1.0.0 

type SocketUpstreamConfig struct {
	Config    service.Configuration `json:"config"`
	CreatedAt time.Time             `json:"created_at"`
	UpdatedAt time.Time             `json:"updated_at"`
}

SocketUpstreamConfig represents an upstream configuration for a socket.

type SocketUpstreamConfigs added in v1.0.0 

type SocketUpstreamConfigs struct {
	List []SocketUpstreamConfig `json:"list"`
}

SocketUpstreamConfigs represents a list of upstream configurations for a socket.

Source Files

View all Source files

Directories

Path Synopsis

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.