jwksproxyhttp

type Binding ¶

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

Binding — объявленная привязка «издатель → путь → обработчик».

func NewBinding(records []Record) (Binding, error)

func (b Binding) PathOf(issuer string) (string, bool)

func (b Binding) Paths() []string

type Config ¶

type Config struct {
	// UpstreamURL — the Hydra PUBLIC JWKS URL to mirror (config.ResolveHydraJWKSURL).
	UpstreamURL string
	// Client — optional injectable http.Client. nil → an internal client WITH a
	// per-call Timeout (never http.DefaultClient).
	Client *http.Client
	// TTL — cache lifetime when the upstream advertises no Cache-Control max-age.
	// <=0 → defaultTTL (5m).
	TTL time.Duration
	// Timeout — per-call upstream-fetch timeout. <=0 → defaultTimeout (5s).
	Timeout time.Duration
	// Clock — injectable time source (tests). nil → time.Now.
	Clock func() time.Time
	// Logger — nil → slog.Default().
	Logger *slog.Logger
}

Config — inputs for the JWKS-proxy handler.

type Handler ¶

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

Handler — the caching reverse-proxy handler.

func NewHandler(cfg Config) *Handler

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (h *Handler) Stats() MirrorStats

type KeySetConfig ¶

type KeySetConfig struct {
	Source KeySetSource
	Logger *slog.Logger
}

KeySetConfig — настройка обработчика нашей записи.

type KeySetHandler ¶

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

KeySetHandler — НАША запись публикуемого набора: ПРОЕКЦИЯ ключницы.

Почему проекция, а не собственный кэш ¶

Порядок «ключ в наборе раньше, чем им подписан первый токен» становится верен ПО ПОСТРОЕНИЮ: опубликованный и подписывающий читаются из одних и тех же строк, и состояния, в котором ключ подписывает, а в ответе его нет, не существует — его не допускает схема.

Собственный кэш вернул бы состояние «строка есть, в ответе нет», и тогда вступление ключа в подпись пришлось бы гейтить на видимость eventually-consistent проекции — запрещённый подтверждающий барьер. С несколькими репликами публикатора «ответ эндпоинта» перестал бы быть одной величиной.

Цена решения названа ¶

Каждый запрос публикации становится чтением своей базы. Величина ограничена сверху числом потребителей, помноженным на частоту их перезапроса, — то есть единицами запросов в минуту, а не функцией от пользовательской нагрузки.

func NewKeySetHandler(cfg KeySetConfig) *KeySetHandler

func (h *KeySetHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (h *KeySetHandler) Stats() KeySetStats

type KeySetSource ¶

type KeySetSource interface {
	PublishedSet(ctx context.Context) ([]domain.PublishedKey, error)
}

KeySetSource — источник НАШЕЙ записи публикуемого набора.

Реализуется ключницей. Порт назван здесь, у вызывающего: публикатор не знает ни про базу, ни про обёртку приватной половины — да и не может знать, потому что тип, которым ключ сюда приезжает, поля приватной половины не имеет вовсе.

type KeySetStats ¶

type KeySetStats struct {
	Served      uint64
	Unavailable uint64
	Empty       uint64
}

KeySetStats — величины по каждому исходу.

«Ноль отказов за всё время жизни» обязано быть отличимо от «контроль не исполнялся», поэтому величины читаются всегда, включая нулевые.

type MirrorStats ¶

type MirrorStats struct {
	// Served — fetches that produced a keyset (a cache hit serves without a fetch
	// and is not counted here; this counts what came off the hop).
	Served uint64
	// Unavailable — fetches refused because the provider did not answer usefully.
	Unavailable uint64
	// Misconfigured — fetches refused because the address does not serve a JWKS.
	Misconfigured uint64
}

MirrorStats — what this mirror has actually done since the process started.

It exists to answer "has this control ever refused anything, and for which reason?". Without the counts, a mirror that has fail-closed on every fetch since the stand came up is indistinguishable from one that never had to — and the difference is "every docker pull is 401" versus "everything is fine".

WHO READS THIS. The composition root registers a scrape collector over these counters (kaname_jwks_mirror_outcomes_total), so Served is published beside the two refusal reasons and "never refused" stays distinguishable from "never reached". Здесь стояло «процесс сообщает их в журнале жизненного цикла» — такого читателя в дереве не было НИ ОДНОГО, то есть комментарий описывал наблюдаемость, которой не существовало, и именно поэтому её отсутствие никого не смутило. Свойство «читатель есть» держит гейт по дереву TestDeclaredAccumulatorsHaveANonTestReader.

type Record ¶

type Record struct {
	// Issuer — принимаемый издатель. Ключ поиска, и ТОЛЬКО ключ поиска.
	Issuer string
	// Path — путь записи. ОБЪЯВЛЯЕТСЯ здесь, а не выводится из издателя.
	//
	// Производная конструкция «взять базовый адрес и приклеить издателя»
	// короче и запрещена по двум причинам сразу. Первая — про безопасность:
	// издатель приходит от предъявителя, то есть это недоверенный вход, и
	// значению от предъявителя не место в построении пути. Вторая — про
	// проверяемость: производный путь получается У ВСЯКОГО издателя, поэтому
	// состояние «записи источника нет» не наступает никогда, и страж старта
	// становится тождественно истинным — проверка остаётся в тексте, не имея
	// возможности упасть.
	Path string
	// Handler — обработчик записи: проекция ключницы для нашей, зеркало для
	// прежнего издателя.
	Handler http.Handler
}

Record — одна запись привязки «издатель → источник набора».

Записей больше одной, и это следствие решения принимать двух издателей: у КАЖДОГО принимаемого издателя своя запись. Объединение наборов рассмотрено и отвергнуто — оно уничтожает ровно ту защиту, ради которой развязка и заводится: ключ одного издателя проверял бы токен, объявляющий другого.