Documentation
¶
Overview ¶
Package app wires the Orca runtime: origin + cachestore + cluster + fetch coordinator + edge / internal HTTP listeners.
Production callers (cmd/orca/orca/orca.go) drive this from a YAML config; integration tests (internal/orca/inttest) drive it from a programmatic *config.Config plus options that inject in-memory or counting decorators around the origin / cachestore.
Index ¶
- type App
- type Option
- func WithCacheStore(cs cachestore.CacheStore) Option
- func WithEdgeListener(ln net.Listener) Option
- func WithInternalHandlerWrap(wrap func(http.Handler) http.Handler) Option
- func WithInternalListener(ln net.Listener) Option
- func WithLogger(log *slog.Logger) Option
- func WithOpsListener(ln net.Listener) Option
- func WithOrigin(or origin.Origin) Option
- func WithPeerSource(s cluster.PeerSource) Option
- func WithSkipCachestoreSelfTest() Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
// EdgeAddr is the resolved client-edge listen address (host:port).
// When the config requested ":0" the port is the OS-assigned one.
EdgeAddr string
// InternalAddr is the resolved peer-RPC listen address (host:port).
InternalAddr string
// OpsAddr is the resolved /healthz + /readyz listen address.
OpsAddr string
// Cluster is exposed so tests can inspect peer state and call
// Coordinator/Self for assertions. Production callers should treat
// this as read-only.
Cluster *cluster.Cluster
// contains filtered or unexported fields
}
App is a running Orca instance.
Construct with Start; tear down with Shutdown. Start is non-blocking: the returned App's listeners are accepting connections (via net.Listen) before Start returns, so EdgeAddr / InternalAddr / OpsAddr are resolved (including any :0 ports) by the time the caller sees them.
func Start ¶
Start wires every dependency and begins serving on the configured listeners. It returns once all listeners are accepting connections (or returns the error that prevented startup).
The returned App must be Shutdown by the caller; Start does not own the parent context's lifetime.
Ordering note: cluster.New is called before any listener is bound. Peers can therefore attempt internal-fill RPCs against this replica before its listener is accepting; those connects fail and the requester falls back to local fill via fetch.Coordinator.GetChunk's peer-fallback path. This is transient (sub-second between cluster construction and listener bind) and harmless.
func (*App) Shutdown ¶
Shutdown gracefully stops every listener and the cluster goroutine. It is safe to call multiple times; subsequent calls are no-ops.
func (*App) Wait ¶
Wait blocks until either the parent context is canceled or one of the listeners exits unexpectedly. It returns the first listener error (if any) or nil if ctx was canceled. Wait is intended for the production "serve until SIGTERM" path; tests typically call Shutdown directly.
Any listener errors that arrive concurrently with the wait-return (ctx-cancel branch or first-error branch) are drained and logged at Warn so they aren't silently discarded. Without this, a shutdown that overlaps with a listener failure - or a multi- listener crash where two listeners errored within the same tick - would lose all but the first error.
Priority: when ctx is already canceled at the time Wait is called, the ctx-cancel branch is taken deterministically even if errCh also has buffered errors. Go's select non-determinism would otherwise flip the return value between nil and a buffered error on a tick race, contradicting the documented "nil if ctx was canceled" contract. The buffered errors are still logged via drainErrCh; only their effect on Wait's return value is suppressed in this specific overlap.
type Option ¶
type Option func(*options)
Option configures Start.
func WithCacheStore ¶
func WithCacheStore(cs cachestore.CacheStore) Option
WithCacheStore replaces the cachestore driver constructed from cfg. Tests use this to wire a counting / fault-injecting decorator around a real s3 client (or to use an in-memory implementation).
func WithEdgeListener ¶
WithEdgeListener supplies a pre-bound listener for the client-edge HTTP server, bypassing app.Start's own net.Listen call.
TEST-ONLY: production callers must not use this option. It is exposed for integration tests (internal/orca/inttest) that allocate the listener before the app starts so peer sets can advertise the captured port from t=0 without a close-and-rebind race. Using it in production silently disables the cfg.Server.Listen address.
func WithInternalHandlerWrap ¶
WithInternalHandlerWrap installs a decorator around the internal peer-RPC handler. The wrap function receives the production handler and returns one that the http.Server actually serves. Production passes nothing -> identity. Tests use this to count 409 responses per source IP for the not-coordinator fallback assertion.
func WithInternalListener ¶
WithInternalListener supplies a pre-bound listener for the peer-RPC internal HTTP server.
TEST-ONLY: see WithEdgeListener.
func WithLogger ¶
WithLogger overrides the slog.Logger used for the App's output. If not provided, a JSON handler writing to stdout at LevelInfo is used.
func WithOpsListener ¶
WithOpsListener supplies a pre-bound listener for the ops HTTP server (/healthz, /readyz).
TEST-ONLY: see WithEdgeListener.
func WithOrigin ¶
WithOrigin replaces the origin driver constructed from cfg. Tests use this to wire counting / fault-injecting decorators around a real awss3 or azureblob client.
func WithPeerSource ¶
func WithPeerSource(s cluster.PeerSource) Option
WithPeerSource replaces the cluster's entire peer-discovery mechanism. Intended for integration tests that need full control (e.g. per-replica peer sets with explicit ports). Only one such override is meaningful per App; subsequent calls overwrite.
func WithSkipCachestoreSelfTest ¶
func WithSkipCachestoreSelfTest() Option
WithSkipCachestoreSelfTest disables the boot-time cachestore self-test. Useful only in tests that wire a cachestore decorator already known to provide read-after-write visibility.
Source Files