notifications

Documentation

Index

• Constants
• Variables
• func Listen(repo distribution.Repository, listener Listener) distribution.Repository
• type ActorRecord
• type BlobListener
• type Broadcaster
  • func NewBroadcaster(sinks ...Sink) *Broadcaster
  • func (b *Broadcaster) Close() error
  • func (b *Broadcaster) Write(events ...Event) error
• type Endpoint
  • func NewEndpoint(name, url string, config EndpointConfig) *Endpoint
  • func (e *Endpoint) Name() string
  • func (e *Endpoint) ReadMetrics(em *EndpointMetrics)
  • func (e *Endpoint) URL() string
• type EndpointConfig
• type EndpointMetrics
• type Envelope
• type Event
• type Listener
  • func NewBridge(ub URLBuilder, source SourceRecord, actor ActorRecord, request RequestRecord, ...) Listener
• type ManifestListener
• type RequestRecord
  • func NewRequestRecord(id string, r *http.Request) RequestRecord
• type Sink
• type SourceRecord
• type URLBuilder

Constants

const (
	EventActionPull   = "pull"
	EventActionPush   = "push"
	EventActionMount  = "mount"
	EventActionDelete = "delete"
)

EventAction constants used in action field of Event.

const (
	// EventsMediaType is the mediatype for the json event envelope. If the
	// Event, ActorRecord, SourceRecord or Envelope structs change, the version
	// number should be incremented.
	EventsMediaType = "application/vnd.docker.distribution.events.v1+json"
)

Variables

var (
	// ErrSinkClosed is returned if a write is issued to a sink that has been
	// closed. If encountered, the error should be considered terminal and
	// retries will not be successful.
	ErrSinkClosed = fmt.Errorf("sink: closed")
)

Functions

func Listen

func Listen(repo distribution.Repository, listener Listener) distribution.Repository

Listen dispatches events on the repository to the listener.

Types

type ActorRecord

type ActorRecord struct {
	// Name corresponds to the subject or username associated with the
	// request context that generated the event.
	Name string `json:"name,omitempty"`
}

ActorRecord specifies the agent that initiated the event. For most situations, this could be from the authorization context of the request. Data in this record can refer to both the initiating client and the generating request.

type BlobListener

type BlobListener interface {
	BlobPushed(repo reference.Named, desc distribution.Descriptor) error
	BlobPulled(repo reference.Named, desc distribution.Descriptor) error
	BlobMounted(repo reference.Named, desc distribution.Descriptor, fromRepo reference.Named) error
	BlobDeleted(repo reference.Named, desc digest.Digest) error
}

BlobListener describes a listener that can respond to layer related events.

type Broadcaster

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

Broadcaster sends events to multiple, reliable Sinks. The goal of this component is to dispatch events to configured endpoints. Reliability can be provided by wrapping incoming sinks.

func NewBroadcaster

func NewBroadcaster(sinks ...Sink) *Broadcaster

NewBroadcaster ... Add appends one or more sinks to the list of sinks. The broadcaster behavior will be affected by the properties of the sink. Generally, the sink should accept all messages and deal with reliability on its own. Use of EventQueue and RetryingSink should be used here.

func (*Broadcaster) Close

func (b *Broadcaster) Close() error

Close the broadcaster, ensuring that all messages are flushed to the underlying sink before returning.

func (*Broadcaster) Write

func (b *Broadcaster) Write(events ...Event) error

Write accepts a block of events to be dispatched to all sinks. This method will never fail and should never block (hopefully!). The caller cedes the slice memory to the broadcaster and should not modify it after calling write.

type Endpoint

type Endpoint struct {
	Sink

	EndpointConfig
	// contains filtered or unexported fields
}

Endpoint is a reliable, queued, thread-safe sink that notify external http services when events are written. Writes are non-blocking and always succeed for callers but events may be queued internally.

func NewEndpoint

func NewEndpoint(name, url string, config EndpointConfig) *Endpoint

NewEndpoint returns a running endpoint, ready to receive events.

func (*Endpoint) Name

func (e *Endpoint) Name() string

Name returns the name of the endpoint, generally used for debugging.

func (*Endpoint) ReadMetrics

func (e *Endpoint) ReadMetrics(em *EndpointMetrics)

ReadMetrics populates em with metrics from the endpoint.

func (*Endpoint) URL

func (e *Endpoint) URL() string

URL returns the url of the endpoint.

type EndpointConfig

type EndpointConfig struct {
	Headers           http.Header
	Timeout           time.Duration
	Threshold         int
	Backoff           time.Duration
	IgnoredMediaTypes []string
	Transport         *http.Transport `json:"-"`
}

EndpointConfig covers the optional configuration parameters for an active endpoint.

type EndpointMetrics

type EndpointMetrics struct {
	Pending   int            // events pending in queue
	Events    int            // total events incoming
	Successes int            // total events written successfully
	Failures  int            // total events failed
	Errors    int            // total events errored
	Statuses  map[string]int // status code histogram, per call event
}

EndpointMetrics track various actions taken by the endpoint, typically by number of events. The goal of this to export it via expvar but we may find some other future solution to be better.

type Envelope

type Envelope struct {
	// Events make up the contents of the envelope. Events present in a single
	// envelope are not necessarily related.
	Events []Event `json:"events,omitempty"`
}

Envelope defines the fields of a json event envelope message that can hold one or more events.

type Event

type Event struct {
	// ID provides a unique identifier for the event.
	ID string `json:"id,omitempty"`

	// Timestamp is the time at which the event occurred.
	Timestamp time.Time `json:"timestamp,omitempty"`

	// Action indicates what action encompasses the provided event.
	Action string `json:"action,omitempty"`

	// Target uniquely describes the target of the event.
	Target struct {
		distribution.Descriptor

		// Length in bytes of content. Same as Size field in Descriptor.
		// Provided for backwards compatibility.
		Length int64 `json:"length,omitempty"`

		// Repository identifies the named repository.
		Repository string `json:"repository,omitempty"`

		// FromRepository identifies the named repository which a blob was mounted
		// from if appropriate.
		FromRepository string `json:"fromRepository,omitempty"`

		// URL provides a direct link to the content.
		URL string `json:"url,omitempty"`

		// Tag provides the tag
		Tag string `json:"tag,omitempty"`
	} `json:"target,omitempty"`

	// Request covers the request that generated the event.
	Request RequestRecord `json:"request,omitempty"`

	// Actor specifies the agent that initiated the event. For most
	// situations, this could be from the authorization context of the request.
	Actor ActorRecord `json:"actor,omitempty"`

	// Source identifies the registry node that generated the event. Put
	// differently, while the actor "initiates" the event, the source
	// "generates" it.
	Source SourceRecord `json:"source,omitempty"`
}

Event provides the fields required to describe a registry event.

type Listener

type Listener interface {
	ManifestListener
	BlobListener
}

Listener combines all repository events into a single interface.

func NewBridge

func NewBridge(ub URLBuilder, source SourceRecord, actor ActorRecord, request RequestRecord, sink Sink) Listener

NewBridge returns a notification listener that writes records to sink, using the actor and source. Any urls populated in the events created by this bridge will be created using the URLBuilder. TODO(stevvooe): Update this to simply take a context.Context object.

type ManifestListener

type ManifestListener interface {
	ManifestPushed(repo reference.Named, sm distribution.Manifest, options ...distribution.ManifestServiceOption) error
	ManifestPulled(repo reference.Named, sm distribution.Manifest, options ...distribution.ManifestServiceOption) error
	ManifestDeleted(repo reference.Named, dgst digest.Digest) error
}

ManifestListener describes a set of methods for listening to events related to manifests.

type RequestRecord

type RequestRecord struct {
	// ID uniquely identifies the request that initiated the event.
	ID string `json:"id"`

	// Addr contains the ip or hostname and possibly port of the client
	// connection that initiated the event. This is the RemoteAddr from
	// the standard http request.
	Addr string `json:"addr,omitempty"`

	// Host is the externally accessible host name of the registry instance,
	// as specified by the http host header on incoming requests.
	Host string `json:"host,omitempty"`

	// Method has the request method that generated the event.
	Method string `json:"method"`

	// UserAgent contains the user agent header of the request.
	UserAgent string `json:"useragent"`
}

RequestRecord covers the request that generated the event.

func NewRequestRecord

func NewRequestRecord(id string, r *http.Request) RequestRecord

NewRequestRecord builds a RequestRecord for use in NewBridge from an http.Request, associating it with a request id.

type Sink

type Sink interface {
	// Write writes one or more events to the sink. If no error is returned,
	// the caller will assume that all events have been committed and will not
	// try to send them again. If an error is received, the caller may retry
	// sending the event. The caller should cede the slice of memory to the
	// sink and not modify it after calling this method.
	Write(events ...Event) error

	// Close the sink, possibly waiting for pending events to flush.
	Close() error
}

Sink accepts and sends events.

type SourceRecord

type SourceRecord struct {
	// Addr contains the ip or hostname and the port of the registry node
	// that generated the event. Generally, this will be resolved by
	// os.Hostname() along with the running port.
	Addr string `json:"addr,omitempty"`

	// InstanceID identifies a running instance of an application. Changes
	// after each restart.
	InstanceID string `json:"instanceID,omitempty"`
}

SourceRecord identifies the registry node that generated the event. Put differently, while the actor "initiates" the event, the source "generates" it.

type URLBuilder

type URLBuilder interface {
	BuildManifestURL(name reference.Named) (string, error)
	BuildBlobURL(ref reference.Canonical) (string, error)
}

URLBuilder defines a subset of url builder to be used by the event listener.