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

type Endpoint struct {
    events.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 []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 events.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 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 19 packages (graph) and is imported by 172 packages. Updated 2020-03-05. Refresh now. Tools for package owners.