forked from mirrors/docker-distribution
Event notification message definition
This commit defines the message format used to notify external parties of activity within a registry instance. The event includes information about which action was taken on which registry object, including what user created the action and which instance generated the event. Message instances can be sent throughout an application or transmitted externally. An envelope format along with a custom media type is defined along with tests to detect changes to the wire format. Signed-off-by: Stephen J Day <stephen.day@docker.com>
This commit is contained in:
Stephen J Day
parent
092dadde6d
commit
af7eb42793
|
|
@ -0,0 +1,122 @@
|
|||
package notifications
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
"github.com/docker/distribution/digest"
|
||||
)
|
||||
|
||||
// EventAction constants used in action field of Event.
|
||||
const (
|
||||
EventActionPull = "pull"
|
||||
EventActionPush = "push"
|
||||
EventActionDelete = "delete"
|
||||
EventActionPing = "ping"
|
||||
)
|
||||
|
||||
// EventsMediaType is the mediatype for the json event envelope. If the Event,
|
||||
// ActorRecord, SourceRecord or Envelope structs change, the version number
|
||||
// should be incremented.
|
||||
const EventsMediaType = "application/vnd.docker.distribution.events.v1+json"
|
||||
|
||||
// Envelope defines the fields of a json event envelope message that can hold
|
||||
// one or more events.
|
||||
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"`
|
||||
}
|
||||
|
||||
// TODO(stevvooe): The event type should be separate from the json format. It
|
||||
// should be defined as an interface. Leaving as is for now since we don't
|
||||
// need that at this time. If we make this change, the struct below would be
|
||||
// called "EventRecord".
|
||||
|
||||
// Event provides the fields required to describe a registry event.
|
||||
type Event struct {
|
||||
// ID provides a unique identifier for the event.
|
||||
ID string `json:"uuid,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 {
|
||||
// Type should be "manifest" or "blob"
|
||||
Type string `json:"type,omitempty"`
|
||||
|
||||
// Name identifies the named repository.
|
||||
Name string `json:"name,omitempty"`
|
||||
|
||||
// Digest should identify the object in the repository.
|
||||
Digest digest.Digest `json:"digest,omitempty"`
|
||||
|
||||
// Tag is present if the operation involved a tagged manifest.
|
||||
Tag string `json:"tag,omitempty"`
|
||||
|
||||
// URL provides a link to the content on the relevant repository instance.
|
||||
URL string `json:"url,omitempty"`
|
||||
} `json:"target,omitempty"`
|
||||
|
||||
// Actor specifies the agent that initiated the event. For most
|
||||
// situations, this could be from the authorizaton 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"`
|
||||
}
|
||||
|
||||
// ActorRecord specifies the agent that initiated the event. For most
|
||||
// situations, this could be from the authorizaton context of the request.
|
||||
type ActorRecord struct {
|
||||
// Name corresponds to the subject or username associated with the
|
||||
// request context that generated the event.
|
||||
Name string `json:"name,omitempty"`
|
||||
|
||||
// Addr contains the ip or hostname and possibly port of the client
|
||||
// connection that initiated the event.
|
||||
Addr string `json:"addr,omitempty"`
|
||||
}
|
||||
|
||||
// SourceRecord identifies the registry node that generated the event. Put
|
||||
// differently, while the actor "initiates" the event, the source "generates"
|
||||
// it.
|
||||
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"`
|
||||
|
||||
// Host is the dns name of the registry cluster, as configured.
|
||||
Host string `json:"host,omitempty"`
|
||||
|
||||
// RequestID uniquely identifies the registry request that generated the
|
||||
// event.
|
||||
RequestID string `json:"request_id,omitempty"`
|
||||
}
|
||||
|
||||
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")
|
||||
)
|
||||
|
||||
// Sink accepts and sends events.
|
||||
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
|
||||
}
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
package notifications
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// TestEventJSONFormat provides silly test to detect if the event format or
|
||||
// envelope has changed. If this code fails, the revision of the protocol may
|
||||
// need to be incremented.
|
||||
func TestEventEnvelopeJSONFormat(t *testing.T) {
|
||||
var expected = strings.TrimSpace(`
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"uuid": "asdf-asdf-asdf-asdf-0",
|
||||
"timestamp": "2006-01-02T15:04:05Z",
|
||||
"action": "push",
|
||||
"target": {
|
||||
"type": "manifest",
|
||||
"name": "library/test",
|
||||
"digest": "sha256:0123456789abcdef0",
|
||||
"tag": "latest",
|
||||
"url": "http://example.com/v2/library/test/manifests/latest"
|
||||
},
|
||||
"actor": {
|
||||
"name": "test-actor",
|
||||
"addr": "hostname.local"
|
||||
},
|
||||
"source": {
|
||||
"addr": "hostname.local",
|
||||
"host": "registrycluster.local",
|
||||
"request_id": "asdfasdf"
|
||||
}
|
||||
},
|
||||
{
|
||||
"uuid": "asdf-asdf-asdf-asdf-1",
|
||||
"timestamp": "2006-01-02T15:04:05Z",
|
||||
"action": "push",
|
||||
"target": {
|
||||
"type": "blob",
|
||||
"name": "library/test",
|
||||
"digest": "tarsum.v2+sha256:0123456789abcdef1",
|
||||
"url": "http://example.com/v2/library/test/manifests/latest"
|
||||
},
|
||||
"actor": {
|
||||
"name": "test-actor",
|
||||
"addr": "hostname.local"
|
||||
},
|
||||
"source": {
|
||||
"addr": "hostname.local",
|
||||
"host": "registrycluster.local",
|
||||
"request_id": "asdfasdf"
|
||||
}
|
||||
},
|
||||
{
|
||||
"uuid": "asdf-asdf-asdf-asdf-2",
|
||||
"timestamp": "2006-01-02T15:04:05Z",
|
||||
"action": "push",
|
||||
"target": {
|
||||
"type": "blob",
|
||||
"name": "library/test",
|
||||
"digest": "tarsum.v2+sha256:0123456789abcdef2",
|
||||
"url": "http://example.com/v2/library/test/manifests/latest"
|
||||
},
|
||||
"actor": {
|
||||
"name": "test-actor",
|
||||
"addr": "hostname.local"
|
||||
},
|
||||
"source": {
|
||||
"addr": "hostname.local",
|
||||
"host": "registrycluster.local",
|
||||
"request_id": "asdfasdf"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
`)
|
||||
|
||||
tm, err := time.Parse(time.RFC3339, time.RFC3339[:len(time.RFC3339)-5])
|
||||
if err != nil {
|
||||
t.Fatalf("error creating time: %v", err)
|
||||
}
|
||||
|
||||
var prototype Event
|
||||
prototype.Action = "push"
|
||||
prototype.Timestamp = tm
|
||||
prototype.Actor.Addr = "hostname.local"
|
||||
prototype.Actor.Name = "test-actor"
|
||||
prototype.Source.Addr = "hostname.local"
|
||||
prototype.Source.Host = "registrycluster.local"
|
||||
prototype.Source.RequestID = "asdfasdf"
|
||||
|
||||
var manifestPush Event
|
||||
manifestPush = prototype
|
||||
manifestPush.ID = "asdf-asdf-asdf-asdf-0"
|
||||
manifestPush.Target.Digest = "sha256:0123456789abcdef0"
|
||||
manifestPush.Target.Type = "manifest"
|
||||
manifestPush.Target.Name = "library/test"
|
||||
manifestPush.Target.Tag = "latest"
|
||||
manifestPush.Target.URL = "http://example.com/v2/library/test/manifests/latest"
|
||||
|
||||
var layerPush0 Event
|
||||
layerPush0 = prototype
|
||||
layerPush0.ID = "asdf-asdf-asdf-asdf-1"
|
||||
layerPush0.Target.Digest = "tarsum.v2+sha256:0123456789abcdef1"
|
||||
layerPush0.Target.Type = "blob"
|
||||
layerPush0.Target.Name = "library/test"
|
||||
layerPush0.Target.URL = "http://example.com/v2/library/test/manifests/latest"
|
||||
|
||||
var layerPush1 Event
|
||||
layerPush1 = prototype
|
||||
layerPush1.ID = "asdf-asdf-asdf-asdf-2"
|
||||
layerPush1.Target.Digest = "tarsum.v2+sha256:0123456789abcdef2"
|
||||
layerPush1.Target.Type = "blob"
|
||||
layerPush1.Target.Name = "library/test"
|
||||
layerPush1.Target.URL = "http://example.com/v2/library/test/manifests/latest"
|
||||
|
||||
var envelope Envelope
|
||||
envelope.Events = append(envelope.Events, manifestPush, layerPush0, layerPush1)
|
||||
|
||||
p, err := json.MarshalIndent(envelope, "", " ")
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error marshaling envelope: %v", err)
|
||||
}
|
||||
if string(p) != expected {
|
||||
t.Fatalf("format has changed\n%s\n != \n%s", string(p), expected)
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue