distribution: github.com/docker/distribution/notifications Index | Files

package notifications

import "github.com/docker/distribution/notifications"

Index

Package Files

bridge.go endpoint.go event.go http.go listener.go metrics.go sinks.go

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")
)

func Listen Uses

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

Listen dispatches events on the repository to the listener.

type ActorRecord Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (b *Broadcaster) Close() error

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

func (*Broadcaster) Write Uses

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 Uses

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 Uses

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

NewEndpoint returns a running endpoint, ready to receive events.

func (*Endpoint) Name Uses

func (e *Endpoint) Name() string

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

func (*Endpoint) ReadMetrics Uses

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

ReadMetrics populates em with metrics from the endpoint.

func (*Endpoint) URL Uses

func (e *Endpoint) URL() string

URL returns the url of the endpoint.

type EndpointConfig Uses

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

EndpointConfig covers the optional configuration parameters for an active endpoint.

type EndpointMetrics Uses

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 Uses

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 Uses

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"`

        // References provides the references descriptors.
        References []distribution.Descriptor `json:"references,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 Uses

type Listener interface {
    ManifestListener
    BlobListener
    RepoListener
}

Listener combines all repository events into a single interface.

func NewBridge Uses

func NewBridge(ub URLBuilder, source SourceRecord, actor ActorRecord, request RequestRecord, sink Sink, includeReferences bool) 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 Uses

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 RepoListener Uses

type RepoListener interface {
    TagDeleted(repo reference.Named, tag string) error
    RepoDeleted(repo reference.Named) error
}

RepoListener provides repository methods that respond to repository lifecycle

type RequestRecord Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

Package notifications imports 18 packages (graph) and is imported by 157 packages. Updated 2019-07-05. Refresh now. Tools for package owners.