Documentation
¶
Overview ¶
Package cloudapi carries the DataTug cloud API client's host failover.
The API is served by one Cloud Run service under several hostnames (a primary behind Cloudflare and a DNS-only fallback). Transport sits under an *http.Client and retries a request on the next host when the current one cannot answer. The rules match the web client's:
- GET and HEAD move on after any network error before a response and after HTTP 502, 503, 504 and the Cloudflare origin statuses 520-523, 525, 526.
- Every other method moves on only when the request certainly never reached a server: a DNS, connect or TLS-handshake error that happened before the attempt obtained a connection (an httptrace GotConn or WroteHeaders signal ends that eligibility, whatever the error says), or Cloudflare 521, 522 or 523 (Cloudflare could not open a connection to the origin). Never after 524 (the origin got the request and was too slow), an application 5xx or a 4xx. A body that cannot be replayed (no GetBody) is never resent.
- An attempt that is not the last one must obtain a connection within ConnectTimeout, so a primary that silently drops packets fails over within a short caller deadline. Not obtaining a connection means nothing was sent, so this applies to every method.
- After a failover the fallback is preferred for HoldFor (5 minutes by default), then the primary is tried first again. The preference lives in the process only.
Index ¶
Constants ¶
const DefaultConnectTimeout = 2 * time.Second
DefaultConnectTimeout bounds how long a non-final attempt may spend getting a connection (DNS, TCP and TLS). A healthy path connects in well under a second even on a poor mobile link; 2 s leaves the fallback about half of the 4 s budget of the shortest caller deadline (the aichat decision call) while still tolerating a slow handshake.
const DefaultHoldFor = 5 * time.Minute
DefaultHoldFor is how long the fallback stays preferred after a failover.
Variables ¶
This section is empty.
Functions ¶
func SplitBaseURLs ¶
SplitBaseURLs splits a comma-separated list of API base URLs, trimming blanks. A single URL gives a one-element list; an empty string gives nil.
Types ¶
type Config ¶
type Config struct {
// BaseURLs lists the API base URLs, primary first. Requests are built
// against the first one; the others replace its prefix on failover.
BaseURLs []string
// Next performs each attempt; nil means http.DefaultTransport.
Next http.RoundTripper
// Now is the clock; nil means time.Now.
Now func() time.Time
// HoldFor is how long a fallback stays preferred; zero means DefaultHoldFor.
HoldFor time.Duration
// ConnectTimeout bounds connection setup of every attempt but the last;
// zero means DefaultConnectTimeout and a negative value disables it.
ConnectTimeout time.Duration
// Notice receives one line, once, when the first failover happens. It
// names hosts only, never paths, queries or credentials. Nil is silent.
Notice io.Writer
}
Config configures a Transport.
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport is an http.RoundTripper that fails over between API base URLs.
func NewTransport ¶
NewTransport builds a Transport. With fewer than two base URLs it only forwards requests, so a single-URL configuration behaves as before.
Source Files