Shoppingcart on Humus

The cart's API

Mon, 01 Jan 0001 00:00:00 +0000

The bodies

Start the endpoint package with what the API reads and writes. Its tags become the document’s schemas:

type Cart struct {
	CartID uuid.UUID `json:"cartId" required:"true" format:"uuid"`
	Items []CartItem `json:"items" required:"true"`
	CreatedAt time.Time `json:"createdAt" required:"true"`
	UpdatedAt time.Time `json:"updatedAt" required:"true"`
}

type CartItem struct {
	ItemID uuid.UUID `json:"itemId" required:"true" format:"uuid"`
	CartID uuid.UUID `json:"cartId" required:"true" format:"uuid"`
	ProductID string `json:"productId" required:"true"`
	Quantity int `json:"quantity" required:"true" minimum:"1"`
	UnitPrice float64 `json:"unitPrice" required:"true" minimum:"0"`
	CreatedAt time.Time `json:"createdAt" required:"true"`
	UpdatedAt time.Time `json:"updatedAt" required:"true"`
}

type AddItemRequest struct {
	ProductID string `json:"productId" required:"true" minLength:"1"`
	Quantity int `json:"quantity" required:"true" minimum:"1"`
}

type UpdateItemRequest struct {
	Quantity int `json:"quantity" required:"true" minimum:"1"`
}

An item’s request has no price. The price comes from the catalog, so a client can’t set its own.

Who may do what

Mon, 01 Jan 0001 00:00:00 +0000

Every operation needs a JWT bearer token from the identity provider. Changing a cart needs the scope carts:write too, and a cart is only ever its owner’s.

The claims

The claims the cart reads from a token are a type of its own. HasScope is what auth.RequireScopes asks:

const ScopeWrite = "carts:write"

type Claims struct {
	Subject string `json:"sub"`
	Scope string `json:"scope"`
}

func (c Claims) HasScope(scope string) bool {
	return slices.Contains(strings.Fields(c.Scope), scope)
}

Verifying tokens

Init builds an httpclient client for the key set’s origin, a jwt.RemoteKeySet that fetches the key set with it, and a Verifier of Claims:

The schema

Mon, 01 Jan 0001 00:00:00 +0000

Each service’s schema is a directory of versioned SQL migrations, applied before the service starts by migrate, as a role that owns the schema. The services connect as roles that can only read and write.

The migrations

The cart’s first migration, database/migrations/001_create_carts.sql:

CREATE TABLE carts (
 id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
 owner TEXT NOT NULL CHECK (owner <> ''),
 created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
 updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE cart_items (
 id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
 cart_id UUID NOT NULL REFERENCES carts(id) ON DELETE CASCADE,
 product_id VARCHAR(255) NOT NULL,
 quantity INTEGER NOT NULL CHECK (quantity > 0),
 unit_price DECIMAL(10, 2) NOT NULL CHECK (unit_price >= 0),
 created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
 updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_cart_items_cart_id ON cart_items(cart_id);

The catalog’s, catalog/database/migrations/001_create_products.sql:

The catalog

Mon, 01 Jan 0001 00:00:00 +0000

The catalog is a second humus service, written as the cart is: an openapi/v3 API served by httpserver, on a PostgreSQL database of its own. It has two operations:

GET /products/{productId} answers a product and its price, to a caller with a client certificate the internal CA issued, which is the cart;
PUT /products/{productId} creates or replaces one, for a bearer token with catalog:write.

The bodies and the Store

type Product struct {
	ProductID string `json:"productId" required:"true"`
	UnitPrice float64 `json:"unitPrice" required:"true" minimum:"0" maximum:"99999999.99"`
}

type PutProductRequest struct {
	UnitPrice *float64 `json:"unitPrice" required:"true" nullable:"false" minimum:"0" maximum:"99999999.99"`
}

const maxUnitPrice = 99999999.99

type Store interface {
	GetProduct(ctx context.Context, productID string) (Product, error)
	PutProduct(ctx context.Context, product Product) (Product, error)
}

var (
	ErrProductNotFound = errors.New("product not found")
	ErrUnavailable = errors.New("the database is unavailable")
)

The maximum is what the table’s DECIMAL(10, 2) holds.

Calling the catalog

Mon, 01 Jan 0001 00:00:00 +0000

The cart has one httpclient client for the catalog. Prices and readiness both go through it.

The client’s settings

The cart’s readSettings starts from httpclient.DefaultSettings(), and sets the catalog’s URL, the CA it trusts the catalog through, and the client certificate it presents:

catalog := httpclient.DefaultSettings()
catalog.BaseURL = r.Get(env("CATALOG_URL").Parse(url.Parse).Validate(checkCatalogURL))
catalog.TLS = &tls.Config{
	RootCAs: r.Get(file("CATALOG_CA_FILE").Parse(certPool)),
	GetClientCertificate: r.Get(env("CATALOG_CLIENT_CERT_FILE").Validate(holdsCertificate(s.Host.FS)).FlatMap(func(certFile string) config.Value[clientCertificate] {
		return env("CATALOG_CLIENT_KEY_FILE").Parse(func(keyFile string) (clientCertificate, error) {
			cfg, err := certfile.Config(s.Host.FS, certFile, keyFile)
			if err != nil {
				return nil, err
			}
			return cfg.GetClientCertificate, nil
		})
	})),
}
catalog.Timeout = r.Get(env("CATALOG_TIMEOUT").Parse(time.ParseDuration).Default(catalog.Timeout).Validate(httpclient.CheckTimeout))
catalog.AttemptTimeout = r.Get(env("CATALOG_ATTEMPT_TIMEOUT").Parse(time.ParseDuration).Default(catalog.AttemptTimeout).Validate(httpclient.CheckAttemptTimeout))
catalog.MaxAttempts = r.Get(env("CATALOG_MAX_ATTEMPTS").Parse(strconv.Atoi).Default(catalog.MaxAttempts).Validate(httpclient.CheckMaxAttempts))
catalog.ForwardScenario = true

type clientCertificate = func(*tls.CertificateRequestInfo) (*tls.Certificate, error)

The catalog asks for a client certificate, so its URL must be https:

Init

Mon, 01 Jan 0001 00:00:00 +0000

The cart’s settings

Everything the cart’s Init reads, in one struct:

type settings struct {
	HTTP httpserver.Settings
	Database *pgxpool.Config
	Catalog httpclient.Settings
	KeySet keySetSettings
	JWT jwt.Settings
	FaultTrustScope string
}

type keySetSettings struct {
	URL *url.URL
	Client httpclient.Settings
}

config.Struct sources and checks each one. A bad one makes Init fail, and the cart exits 78, naming its variable:

func readSettings(ctx context.Context, s *humus.Setup) (settings, error) {
	d := httpserver.DefaultSettings()
	env := func(name string) config.Value[string] { return config.Env(s.Process.Environment, name) }
	file := func(name string) config.Value[[]byte] { return env(name).Parse(readFile(s.Host.FS)) }

	read, err := config.Struct(func(r *config.Resolver) settings {
		client := httpclient.DefaultSettings()
		client.TLS = r.Get(file("JWKS_CA_FILE").Parse(certPool).Default(nil).Map(func(roots *x509.CertPool) *tls.Config {
			return &tls.Config{RootCAs: roots}
		}))
		client.Timeout = r.Get(env("JWKS_TIMEOUT").Parse(time.ParseDuration).Default(client.Timeout).Validate(httpclient.CheckTimeout))
		client.AttemptTimeout = r.Get(env("JWKS_ATTEMPT_TIMEOUT").Parse(time.ParseDuration).Default(client.AttemptTimeout).Validate(httpclient.CheckAttemptTimeout))
		client.MaxAttempts = r.Get(env("JWKS_MAX_ATTEMPTS").Parse(strconv.Atoi).Default(client.MaxAttempts).Validate(httpclient.CheckMaxAttempts))

The catalog’s client comes next, as Calling the catalog shows, then the tokens’ settings and the server’s:

Testing

Mon, 01 Jan 0001 00:00:00 +0000

The cart’s unit tests

The cart’s Init opens its Store and its Catalog through two functions:

func Init(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
	return initWith(ctx, s, openPostgres, openCatalog)
}

type openStore func(ctx context.Context, s *humus.Setup, cfg *pgxpool.Config) (store endpoint.Store, ping func(context.Context) error, err error)

type newCatalog func(s *humus.Setup, settings httpclient.Settings) (catalog endpoint.Catalog, ready func(context.Context) error, err error)

So its unit tests give it a Store in memory and a fake catalog, which answers from a price list, or fails when the test says so:

Deploying

Mon, 01 Jan 0001 00:00:00 +0000

The image

One image holds the cart, the catalog and migrate. A Go stage builds each of them static, and the image copies them to /cart, /catalog and /migrate on a distroless base, to run as the non-root user 65532. example/http/shoppingcart/Dockerfile names the exact images and their versions.

Build it from the repository’s root, since the module replaces humus with its directory:

docker build --file example/http/shoppingcart/Dockerfile --tag shoppingcart .

The kustomization

deploy/base holds the namespace, a ServiceAccount, a Deployment, a Service and a disruption budget for each service, and each one’s settings:

Observing

Mon, 01 Jan 0001 00:00:00 +0000

Opening Grafana

up.sh generates Grafana’s admin password into the grafana-admin Secret. Read it, then forward Grafana’s port:

kubectl --context kind-kind --namespace shoppingcart get secret grafana-admin \
 --output jsonpath='{.data.password}' | base64 --decode
kubectl --context kind-kind --namespace shoppingcart port-forward service/grafana 3000:3000

An add’s trace

Add an item to a cart, as Deploying shows. Each server span is named after its method and the operation’s route, so in Explore, with Tempo, find the adds by their name:

Production-ready

Mon, 01 Jan 0001 00:00:00 +0000

The cart and the catalog meet each item. Check your own API against them:

Item	How	Where
Every setting sourced and checked; a bad one exits 78, naming its variable	`config.Struct` and the packages’ checks, in the cart, the catalog and `migrate`	The cart’s settings, The other checks, `migrate`’s settings
No secret in the environment, the logs or the spans	the database URLs and the keys are files, read through `s.Host.FS`. No token is recorded, which a test of the App checks	The secrets, as files, Their log records
Certificates renewed without a restart	`internal/certfile`, on the `kubernetes.io/tls` Secrets that cert-manager renews. Its unit tests rewrite the files under a running server	The certificates, read again when renewed
Two replicas of each service	a PodDisruptionBudget of `minAvailable: 1`, and a rolling update of `maxUnavailable: 0`	The Deployments, The disruption budgets
Ready only once it has reached its dependencies, and still ready through their outages	the latching monitors, on PostgreSQL and on the catalog’s readiness	Readiness, The catalog’s probes, The cart’s readiness
A rollout loses no request	`httpserver.Main`’s 5s drain, in both services, and a `terminationGracePeriodSeconds` above the drain, the grace period and the telemetry’s shutdown	The drain
The schema is current before the code that needs it serves	the `migrate` init container, under tern’s lock, with backwards-compatible migrations	The migrations, The job, The init container
Least privilege	the services’ roles read and write their tables and change no schema. A non-root, read-only container. No service account token mounted	The grant, The roles, The Deployments
A caller sees only their own carts	the owner, from the token’s subject, and a 404 for anyone else	A cart’s owner
Prices can’t be set by a client	the cart asks the catalog for each price, over mTLS. Only a token with `catalog:write` changes one	The bodies, mTLS, The operations
Observable	traces across both services, logs and metrics over OTLP, the alerts in `deploy/alerts.yaml`, `deploy/dashboard.json`, and alerts on each Deployment from the Collector’s Kubernetes cluster receiver	Observing
Failures say why	a 503 for a dependency that is down, a 422 for an unknown product, and problem details throughout	The answers, The catalog’s answers
Failures are rehearsed	the failure injection cases, in CI, and against an end user’s staging through its own `Target`	The shared cases, The failure injection cases
Safe by default	`FAULT_TRUST_SCOPE` empty, so no scenario is trusted. The OpenAPI document is the only open path besides the probes	`TrustScenario`, Requiring it