diderot

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

type ADSClientOption func(*options)

type ADSServer struct {
	discovery.UnimplementedAggregatedDiscoveryServiceServer
	// contains filtered or unexported fields
}

type ADSServerOption interface {
	// contains filtered or unexported methods
}

type Cache[T proto.Message] interface {
	RawCache
	// Set stores the given resource in the cache. If the resource name corresponds to a resource URN, it
	// will also be stored in the corresponding glob collection (see [TP1 proposal] for additional
	// details on the format). See Subscribe for more details on how the resources added by this method
	// can be subscribed to. Invoking Set whenever possible is preferred to RawCache.SetRaw, since it can
	// return an error if the given resource's type does not match the expected type while Set validates
	// at compile time that the given value matches the desired type. A zero [time.Time] can be used to
	// represent that the time at which the resource was created or modified is unknown (or ignored).
	//
	// WARNING: It is imperative that the Resource and the underlying [proto.Message] not be modified
	// after insertion! This resource will be read by subscribers to the cache and callers of Get, and
	// modifying the resource may at best result in incorrect reads for consumers and at worst panics if
	// the consumer is reading a map as it's being modified. When in doubt, callers should pass in a deep
	// copy of the resource. Note that the cache takes no responsibility in enforcing this since cloning
	// every resource as it is inserted in the cache may incur unexpected and avoidable costs.
	//
	// [TP1 proposal]: https://github.com/cncf/xds/blob/main/proposals/TP1-xds-transport-next.md#uri-based-xds-resource-names
	Set(name, version string, t T, modifiedAt time.Time) *ads.Resource[T]
	// SetResource is the more verbose equivalent of Set which supports the additional fields in [ads.Resource].
	SetResource(r *ads.Resource[T], modifiedAt time.Time)
	// Get fetches the entry, or nil if it's not present and/or has been deleted.
	Get(name string) *ads.Resource[T]
	// IsSubscribedTo checks whether the given handler is subscribed to the given named entry.
	IsSubscribedTo(name string, handler ads.SubscriptionHandler[T]) bool
	// Subscribe registers the handler as a subscriber of the given named resource. The handler is always
	// immediately called with the current values of the entries selected by this call, even if it was
	// already subscribed.
	//
	// If the name is ads.WildcardSubscription, the handler is registered as a wildcard subscriber. This
	// means the handler will be subscribed to all existing entries, and be automatically subscribed to
	// any new entries until a corresponding call to Unsubscribe is made.
	//
	// If the name is a glob collection URL, the handler will be subscribed to all entries in the
	// collection, along with being automatically subscribed to any new entries. If the collection is
	// empty, the handler will receive a deletion notification for the entire collection. This behavior
	// is defined in the [TP1 proposal]:
	//	If no resources are present in the glob collection, the server should reply with a
	//	DeltaDiscoveryResponse in which the glob collection URL is specified in removed_resources.
	// The subscription will be preserved even if the glob collection is empty (or becomes empty) until a
	// corresponding call to Unsubscribe is made.
	//
	// Otherwise, the handler will be subscribed to the resource specified by the given name and receive
	// notifications any time the resource changes. If a resource by that name does not exist, the
	// handler will immediately receive a deletion notification, but will not be unsubscribed until a
	// corresponding call to Unsubscribe is made. See the [spec on deletions] for more details.
	//
	// Note that there are therefore three ways to subscribe to a given resource:
	//  1. The simplest way is to explicitly subscribe to a resource, via its name. Such a subscription is
	//     it can only be cancelled with a corresponding call to Unsubscribe. It will not, for example, be
	//     cancelled by unsubscribing from the wildcard. This is by design, as it allows clients to discover
	//     resources by emitting a wildcard subscription, finding which resources they are interested in,
	//     explicitly subscribing to those then removing the implicit subscriptions to other resources by
	//     unsubscribing from the wildcard. This is outlined in the [sample xDS flows].
	//  2. If the resource's name is a URN, a subscription to the matching glob collection URL will
	//     subscribe the given handler to the resource. Similar to the explicit subscription listed in 1.,
	//     unsubscribing from the wildcard will not cancel a glob collection to a resource, only a
	//     corresponding unsubscription to the collection will cancel it.
	//  3. A wildcard subscription will also implicitly create a subscription to the resource.
	//     subscribe
	//
	// Note that while the xDS docs are clear on what the behavior should be when a subscription is
	// "upgraded" from a wildcard subscription to an explicit subscription, they are not clear as to what
	// happens when a subscription is "downgraded". For example, if a client subscribes to a resource "A"
	// then subscribes to the wildcard, should an unsubscription from the wildcard cancel the
	// subscription to "A"? Similarly, the docs are unclear as to what should happen if a client
	// subscribes to the wildcard, then subscribes to resource "A", then unsubscribes from "A". Should
	// the original implicit subscription to "A" via the wildcard be honored? To address both of these,
	// the cache will preserve all subscriptions that target a specific resource. This means a client that
	// subscribed to a resource both via a wildcard and an explicit subscription (regardless of order) will
	// only be unsubscribed from that resource once it has both explicitly unsubscribed from the resource and
	// unsubscribed from the wildcard (regardless of order).
	//
	// It is unsafe for multiple goroutines to invoke Subscribe and/or Unsubscribe with the same
	// SubscriptionHandler, and will result undefined behavior.
	//
	// [TP1 proposal]: https://github.com/cncf/xds/blob/main/proposals/TP1-xds-transport-next.md#glob
	// [sample xDS flows]: https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol#how-the-client-specifies-what-resources-to-return
	// [spec on deletions]: https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol#id2
	Subscribe(name string, handler ads.SubscriptionHandler[T])
	// Unsubscribe removes the given handler from the named entry's list of subscribers.
	//
	// If the given name is ads.WildcardSubscription, the handler is unsubscribed from all entries it did
	// not explicitly subscribe to (see definition of explicit subscription in Subscribe).
	//
	// If the given name is a glob collection URL, it is unsubscribed from the collection, unsubscribing
	// it from all matching entries.
	//
	// Noop if the resource does not exist or the handler was not subscribed to it.
	Unsubscribe(name string, handler ads.SubscriptionHandler[T])
}

type RawCache interface {
	// Type returns the corresponding [Type] for this cache.
	Type() Type
	// EntryNames returns an [iter.Seq] that will iterate over all the current entry names in the cache.
	EntryNames() iter.Seq[string]
	// GetRaw is the untyped equivalent of Cache.Get. There are uses for this method, but the preferred
	// way is to use Cache.Get because this function incurs the cost of marshaling the resource. Returns
	// an error if the resource cannot be marshaled.
	GetRaw(name string) (*ads.RawResource, error)
	// SetRaw is the untyped equivalent of Cache.Set. There are uses for this method, but the preferred
	// way is to use Cache.Set since it offers a typed API instead of the untyped ads.RawResource parameter.
	// Subscribers will be notified of the new version of this resource. See Cache.Set for additional
	// details on how the resources are stored. Returns an error if the given resource's type URL does
	// not match the expected type URL, or the resource cannot be unmarshaled.
	SetRaw(r *ads.RawResource, modifiedAt time.Time) error
	// Clear clears the entry (if present) and notifies all subscribers that the entry has been deleted.
	// A zero [time.Time] can be used to represent that the time at which the resource was cleared is
	// unknown (or ignored). For example, when watching a directory, the filesystem does not keep track
	// of when the file was deleted.
	Clear(name string, clearedAt time.Time)
	// EstimateSubscriptionSize estimates the number of resources targeted by the given list of
	// subscriptions. This is only an estimation since the resource count is dynamic, and repeated
	// invocations of this function with the same parameters may not yield the same results.
	EstimateSubscriptionSize(resourceNamesSubscribe []string) int
}

type ResourceLocator interface {
	// Subscribe subscribes the given handler to the desired resource. The returned function should
	// execute the unsubscription to the resource. The desired behavior when a client resubscribes to a
	// resource is for the resource to be re-sent. To achieve this, the returned unsubscription function
	// will be called, then [Subscribe] will be called again with the same parameters. Additionally, this
	// function should only return when the given subscription handler has received the notification(s)
	// for the corresponding subscription(s). It allows the server implementation to correctly batch
	// resources for more efficient responses, as well as skip the granular limiter (if enabled). This is
	// especially important during the initial bulk subscriptions a client will emit at startup.
	//
	// Note: There is no clear provision in the protocol for what to do if a client sends a request for a
	// type that is unsupported by this server. Therefore, this is not explicitly handled by the Server.
	// Instead, the implementation of this function may choose to either do nothing, or send back a
	// deletion notification for the requested resources whose types are not supported.
	Subscribe(
		streamCtx context.Context,
		typeURL, resourceName string,
		handler ads.RawSubscriptionHandler,
	) (unsubscribe func())
}

type SendBufferSizeEstimator interface {
	// EstimateSubscriptionSize returns the expected number of resources that will be sent back as a
	// result of the given resource names.
	EstimateSubscriptionSize(streamCtx context.Context, typeURL string, resourceNamesSubscribe []string) int
}

type Type interface {
	// URL returns the type URL for this Type.
	URL() string
	// TrimmedURL returns the type URL for this Type without the leading "types.googleapis.com/" prefix.
	// This string is useful when constructing xdstp URLs.
	TrimmedURL() string
	// NewCache is the untyped equivalent of this package's NewCache. The returned RawCache still
	// retains the runtime type information and can be safely cast to the corresponding Cache type.
	NewCache() RawCache
	// NewPrioritizedCache is the untyped equivalent of this package's NewPrioritizedCache. The returned
	// RawCache instances can be safely cast to the corresponding Cache type.
	NewPrioritizedCache(prioritySlots int) []RawCache
	// contains filtered or unexported methods
}

type TypeReference[T proto.Message] interface {
	Type
}

type Watcher[T proto.Message] interface {
	// Notify is invoked whenever a response is processed. The given sequence will iterate over all the
	// resources in the response, with a nil resource indicating a deletion. Implementations should
	// return an error if any resource is invalid, and this error will be propagated as a NACK to the xDS
	// backend.
	Notify(resources iter.Seq2[string, *ads.Resource[T]]) error
}