hostlink

type Admission interface {
	// Draining reports that this Host has begun a drain and is publishing
	// accepting=false, so a new binding must not be established.
	Draining() bool
}

type Authenticator interface {
	VerifyTenant(context.Context, sessionwire.TenantID, string) error
}

type BindError struct {
	// Refusal is which check fired, and is the field an operator reads.
	Refusal Refusal

	// Key is the session the request named, as far as it was parsed.
	Key registry.Key

	// Reason is human-readable detail. It never carries a credential, a
	// payload or another tenant's identifiers.
	Reason string

	// Cause is the typed error a decoder produced, if any.
	Cause error
	// contains filtered or unexported fields
}

type Binding struct {
	Link    LinkID
	Key     registry.Key
	Channel string

	// LeaseEpoch is the epoch the bind VALIDATED against. It is a record of
	// what was true at bind time and confers nothing; the lease itself is the
	// only thing that grants, and this package never touches it.
	LeaseEpoch uint64

	// IdempotencyKey is the most recent retry-stable key the Factory supplied.
	//
	// HOSTLINK DOES NOT DE-DUPLICATE ON IT, and that is a decision rather than
	// an omission: a repeated bind RE-VALIDATES current ownership instead of
	// replaying a cached acceptance, so a retry that arrives after the epoch
	// moved is refused rather than confirmed. Replaying would make the bind a
	// statement about the past, which is the one thing a routing validation
	// must not be. The key is recorded so an operator can correlate a retry
	// storm with one Factory attempt.
	IdempotencyKey string
}

type CommandConsumer interface {
	// Hint wakes consumption of an already accepted command. It is a wake and
	// not a delivery, so repeating it is harmless.
	Hint(sessionwire.CommandID)
}

type CommandConsumers interface {
	// ConsumerFor returns the consumer for a resident session, and whether one
	// is running.
	ConsumerFor(registry.Key) (CommandConsumer, bool)
}

type Config struct {
	TenantID      sessionwire.TenantID
	Authenticator Authenticator

	// PingInterval and PongTimeout are optional but must be supplied together:
	// setting one without the other is rejected. When both are zero HostLink
	// sends no PingPongConfig at all and the heartbeat falls to Centrifuge's
	// own application-level defaults of 25s ping and 10s pong
	// (centrifuge@v0.38.0 config.go:218 and config.go:224) — zero does not mean
	// "no heartbeat". That route held one exception until O5.2 removed it:
	// cf_ws_frame_ping_pong would have moved a zero-configured link onto
	// WebSocket frame ping instead, and rejectedTransportQueryKeys now refuses
	// the key before the upgrade. When supplied, PingInterval must be at least
	// one second and PongTimeout must be strictly shorter than PingInterval.
	PingInterval time.Duration
	PongTimeout  time.Duration

	// Multiplexer is the routing table this server's links bind through. It is
	// optional: a server built without one still authenticates, negotiates and
	// heartbeats, and answers every RPC and subscribe with Centrifuge's own
	// unhandled-command refusal.
	Multiplexer *Multiplexer
}

type DrainObserver interface {
	// ObserveDrain returns the drain covering scope and whether one has begun
	// at all. It never starts one.
	ObserveDrain(DrainScope) (DrainStatus, bool)
}

type DrainScope struct {
	// Key is the fixed session of a dedicated Host. Its zero value means the
	// whole Host, and a partially populated Key is not reachable: the resolver
	// sets both fields or neither.
	Key registry.Key
}

type DrainScopeReporter interface {
	// BegunScope reports the scope the drain was begun with, and whether a
	// drain has begun that named one at all.
	BegunScope() (registry.Key, bool)
}

type DrainStarter interface {
	// StartDrain begins the drain covering scope and reports its stable
	// generation and current state. It is IDEMPOTENT: a call for a drain
	// already begun returns that same generation rather than starting a
	// second one, and it returns promptly rather than waiting for release.
	StartDrain(DrainScope) (DrainStatus, error)
}

type DrainStatus struct {
	// Generation identifies this drain across retries, reconnects and
	// ambiguous replies. Core refuses a zero generation.
	Generation uint64

	// State is Core's bounded drain state. A value outside Core's two is not
	// published; see drainObservation.
	State sessionwire.HostLinkDrainState
}

type InvalidMultiplexerOptionsError struct {
	Field  string
	Reason string
}

type LinkID string

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

type MultiplexerOptions struct {
	// TenantID is the tenant every link on this Multiplexer authenticated as.
	//
	// IT IS THE LINK'S TENANT AND NO LONGER THE HOST'S. Human gate H8, answered
	// 2026-09-04, dropped the fixed tenant from host.Options: a pooled Host
	// advertising cross_tenant_isolated admits several tenants, and one
	// advertising tenant_exclusive is exclusive by PLACEMENT rather than by
	// construction. A composition therefore supplies this from the
	// authenticated service identity of the connection, not from the Host, and
	// a Host serving several tenants runs one Multiplexer per authenticated
	// tenant. The refusal below still says "this link is authenticated for
	// another tenant", which was always the accurate sentence.
	TenantID sessionwire.TenantID

	// HostID and HostGeneration are this Host process's identity and
	// incarnation, compared against every bind.
	HostID         sessionwire.HostID
	HostGeneration uint64

	Residencies Residencies
	Admission   Admission
	Consumers   CommandConsumers

	// DrainStarter and DrainObserver are the drain state machine this Host's
	// HostLink may begin and observe. They are OPTIONAL AND PAIRED: supplying
	// one without the other is refused, because a Host that can be told to
	// drain and cannot be asked how it is going, or the reverse, is a Factory
	// bug discovered in production instead of at construction.
	//
	// Their ABSENCE IS A REFUSAL AND NOT A DEFAULT. A Multiplexer built
	// without them answers both drain RPCs with RefusalDrainUnsupported, so a
	// Host with no drain to run cannot be made to look as though it started
	// one. That is the same shape as Config.Multiplexer's own absence.
	DrainStarter  DrainStarter
	DrainObserver DrainObserver

	// FixedSessionID is the sole session a DEDICATED Host holds, and its zero
	// value means this Host is pooled.
	//
	// It is read by the drain path only. It is NOT a second admission rule:
	// nothing on the bind path consults it, and the dedicated-attach refusal
	// lives in the residency manager where the durable state is. Putting a
	// second copy of "which sessions may this Host hold" on the routing table
	// would be two answers to one question.
	FixedSessionID sessionwire.SessionID

	// MaxBindingsPerLink and MaxBindings bound what one link and the whole
	// Host may hold. A binding is not free — it is a subscription and an
	// enduring-event queue — so an unbounded one is an unbounded Host.
	MaxBindingsPerLink int
	MaxBindings        int
}

type Refusal string

type Residencies interface {
	// Get returns a COPY of the registry row for a key, and whether one is
	// held. registry.Entry is a copy by that package's contract, so a caller
	// mutating the result changes nothing.
	Get(registry.Key) (registry.Entry, bool)
}

type Server interface {
	// Handler serves only clients that select the JSON protocol explicitly,
	// by a sole Sec-WebSocket-Protocol field of centrifuge-json tokens or by a
	// format/cf_protocol query value of json. Anything else, including a
	// request that names no protocol at all, is answered with HTTP 400 before
	// the upgrade; see selectsJSONProtocol for the rule and its provenance.
	Handler() http.Handler

	// Publish puts one payload on one channel.
	//
	// IT REPORTS TRANSPORT ACCEPTANCE AND NOT DELIVERY. A channel nobody has
	// subscribed is not an error: a Factory link that has dropped and not yet
	// reconnected is an ordinary state, and a transport that refused it would
	// make an idle route indistinguishable from a broken one to the caller that
	// decides whether to invalidate it.
	//
	// It is the production side of the seam the live event relay declares. That
	// seam takes a channel and a payload and nothing else, so this signature
	// carries no link, no replica set and no context — the fan-out belongs to
	// the transport, which owns a queue per physical connection, and Host owns
	// the decision to publish once.
	Publish(channel string, payload []byte) error

	Close(context.Context) error
}