Documentation
¶
Overview ¶
Package tier contains the local client for interacting with the tier sidecar API.
For more information, please see https://tier.run/docs.
Index ¶
- Constants
- func WithClock(ctx context.Context, id string) context.Context
- type Answer
- type CheckoutParams
- type Client
- func (c *Client) Advance(ctx context.Context, t time.Time) error
- func (c *Client) Can(ctx context.Context, org, feature string) Answer
- func (c *Client) Cancel(ctx context.Context, org string) error
- func (c *Client) Checkout(ctx context.Context, org string, successURL string, p *CheckoutParams) (*apitypes.CheckoutResponse, error)
- func (c *Client) LookupLimit(ctx context.Context, org, feature string) (limit, used int, err error)
- func (c *Client) LookupLimits(ctx context.Context, org string) (apitypes.UsageResponse, error)
- func (c *Client) LookupOrg(ctx context.Context, org string) (apitypes.WhoIsResponse, error)
- func (c *Client) LookupPaymentMethods(ctx context.Context, org string) (apitypes.PaymentMethodsResponse, error)
- func (c *Client) LookupPhase(ctx context.Context, org string) (apitypes.PhaseResponse, error)
- func (c *Client) LookupPhases(ctx context.Context, org string) (apitypes.PhasesResponse, error)
- func (c *Client) Pull(ctx context.Context) (apitypes.Model, error)
- func (c *Client) PullJSON(ctx context.Context) ([]byte, error)
- func (c *Client) Push(ctx context.Context, m apitypes.Model) (apitypes.PushResponse, error)
- func (c *Client) PushJSON(ctx context.Context, m []byte) (apitypes.PushResponse, error)
- func (c *Client) Report(ctx context.Context, org, feature string, n int) error
- func (c *Client) ReportUsage(ctx context.Context, org, feature string, n int, rp *ReportParams) error
- func (c *Client) Schedule(ctx context.Context, org string, p *ScheduleParams) (*apitypes.ScheduleResponse, error)
- func (c *Client) Subscribe(ctx context.Context, org string, featuresAndPlans ...string) error
- func (c *Client) WhoAmI(ctx context.Context) (apitypes.WhoAmIResponse, error)
- func (c *Client) WhoIs(ctx context.Context, org string) (apitypes.WhoIsResponse, error)
- func (c *Client) WithClock(ctx context.Context, name string, start time.Time) (context.Context, error)
- type OrgInfo
- type Phase
- type ReportParams
- type ScheduleParams
- type Taxation
Examples ¶
Constants ¶
const ClockHeader = "Tier-Clock"
ClockHeader is the header used to pass the clock ID to the tier sidecar. It is exported for use by the sidecar API. Most users want to use WithClock.
const Inf = 1<<63 - 1
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Answer ¶ added in v0.4.2
type Answer struct {
// contains filtered or unexported fields
}
An Answer is the response to any question for Can. It can be used in a few forms to shorten the logic necessary to know if a program should proceed to perform a user request based on their entitlements.
func (Answer) Err ¶ added in v0.4.2
Err returns the error, if any, that occurred during the call to Can.
func (Answer) OK ¶ added in v0.4.2
OK reports if the program should proceed with a user request or not. To prevent total failure if Can needed to reach the sidecar and was unable to, OK will fail optimistically and report true. If the opposite is desired, clients can check Err.
type CheckoutParams ¶ added in v0.7.1
type Client ¶
type Client struct {
// APIKey is the API key used, and set in the Authorization header.
APIKey string
BaseURL string // the base URL of the tier sidecar; default is http://127.0.0.1:8080
HTTPClient *http.Client
Logf func(fmt string, args ...any)
}
Example ¶
package main
import (
"io"
"log"
"net/http"
"tier.run/client/tier"
)
func main() {
c := &tier.Client{}
m := http.NewServeMux()
m.HandleFunc("/convert", func(w http.ResponseWriter, r *http.Request) {
org := orgFromSession(r)
ans := c.Can(r.Context(), org, "feature:convert")
if ans.OK() {
w.WriteHeader(http.StatusTooManyRequests)
return
}
defer ans.Report()
temp := convert(r.FormValue("temp"))
io.WriteString(w, temp)
})
m.HandleFunc("/subscribe", func(w http.ResponseWriter, r *http.Request) {
org := orgFromSession(r)
plan := r.FormValue("plan")
if err := c.Subscribe(r.Context(), org, plan); err != nil {
w.WriteHeader(http.StatusInternalServerError)
return
}
})
log.Fatal(http.ListenAndServe(":https", m))
}
func orgFromSession(r *http.Request) string {
return "org:example"
}
func convert(temp string) string {
return "80F"
}
Output:
func FromEnv ¶ added in v0.7.0
FromEnv returns a Client configured from the environment. The BaseURL is set to the value of the TIER_BASE_URL environment variable, or http://127.0.0.1:8080 if unset.
It returns an error if the TIER_BASE_URL environment variable is set to an invalid URL.
func (*Client) Advance ¶ added in v0.10.0
Advance advances the test clock set in the context to t.
It is an error to call Advance if no clock is set in the context.
func (*Client) Can ¶ added in v0.4.2
Can is a convenience function for checking if an org has used more of a feature than they are entitled to and optionally reporting usage post check and consumption.
If reporting consumption is not required, it can be used in the form:
if c.Can(ctx, "org:acme", "feature:convert").OK() { ... }
reporting usage post consumption looks like:
ans := c.Can(ctx, "org:acme", "feature:convert")
if !ans.OK() {
return ""
}
defer ans.Report() // or ReportN
return convert(temp)
Example (Basic) ¶
package main
import (
"context"
"tier.run/client/tier"
)
func main() {
c := &tier.Client{}
// Check if the user can convert a temperature.
if c.Can(context.Background(), "org:example", "feature:convert").OK() {
// The user can convert a temperature.
} else {
// The user cannot convert a temperature.
}
}
Output:
Example (Report) ¶
package main
import (
"context"
"fmt"
"tier.run/client/tier"
)
func main() {
c := &tier.Client{}
ans := c.Can(context.Background(), "org:example", "feature:convert")
if !ans.OK() {
// The user cannot convert a temperature.
return
}
defer ans.Report() // report consumption after the conversion
fmt.Println(convert(readInput()))
}
func convert(temp string) string {
return "80F"
}
func readInput() string {
return "30C"
}
Output:
func (*Client) Checkout ¶ added in v0.7.1
func (c *Client) Checkout(ctx context.Context, org string, successURL string, p *CheckoutParams) (*apitypes.CheckoutResponse, error)
Checkout creates a new checkout link for the provided org and features, if any; otherwise, if no features are specified, and payment setup link is returned instead.
func (*Client) LookupLimit ¶ added in v0.4.2
LookupLimit reports the current usage and limits for the provided org and feature. If the feature is not currently available to the org, both limit and used are zero and no error is reported.
It reports an error if any.
func (*Client) LookupLimits ¶ added in v0.3.1
LookupLimits reports the current usage and limits for the provided org.
func (*Client) LookupOrg ¶ added in v0.6.0
LookupOrg reports all known information about the provided org. The information is not cached by the server. If only the Stripe customer ID is needed and speed is of concern, users should use WhoIs.
func (*Client) LookupPaymentMethods ¶ added in v0.9.0
func (*Client) LookupPhase ¶ added in v0.4.2
LookupPhase reports information about the current phase the provided org is scheduled in.
func (*Client) LookupPhases ¶
LookupPhases reports information about all recent, current, and future phases for org.
EXPERIMENTAL: This API is subject to change.
func (*Client) PullJSON ¶ added in v0.4.2
PullJSON fetches the complete pricing model from Stripe and returns the raw JSON response.
func (*Client) Report ¶ added in v0.4.2
Report reports a usage of n for the provided org and feature at the current time.
func (*Client) ReportUsage ¶
func (c *Client) ReportUsage(ctx context.Context, org, feature string, n int, rp *ReportParams) error
ReportUsage reports usage based on the provided ReportRequest fields.
func (*Client) Schedule ¶ added in v0.6.0
func (c *Client) Schedule(ctx context.Context, org string, p *ScheduleParams) (*apitypes.ScheduleResponse, error)
func (*Client) Subscribe ¶
Subscribe subscribes the provided org to the provided feature or plan, effective immediately.
Any in-progress scheduled is overwritten and the customer is billed with prorations immediately.
func (*Client) WhoIs ¶
WhoIs reports the Stripe customer ID for the provided org. OrgInfo is not set.
func (*Client) WithClock ¶ added in v0.10.0
func (c *Client) WithClock(ctx context.Context, name string, start time.Time) (context.Context, error)
WithClock creates a new test clock with the provided name and start time, and returns a new context with the clock ID set.
It is an error to call WithClock if a clock is already set in the context.
Example (TestClocks) ¶
package main
import (
"context"
"time"
"tier.run/client/tier"
)
func main() {
c, err := tier.FromEnv()
if err != nil {
panic(err)
}
now := time.Now()
ctx, err := c.WithClock(context.Background(), "testName", now)
if err != nil {
panic(err)
}
// Use ctx with other Client methods
// This creates the customer and subscription using the clock.
_ = c.Subscribe(ctx, "org:example", "plan:free@0")
// Advance the clock by 24 hours, and then report usage.
_ = c.Advance(ctx, now.Add(24*time.Hour))
_ = c.Report(ctx, "org:example", "feature:bandwidth", 1000)
}
Output:
Source Files