prov

Documentation

Index

• Variables
• func PrepareNewActivity(newActivity *NewActivity, traceID string, now time.Time) (Activity, SubGraph)
• func PrepareNewAgent(newAgent *NewAgent, traceID string, now time.Time) (Agent, SubGraph)
• func PrepareNewEntity(newEntity *NewEntity, traceID string, now time.Time) (Entity, SubGraph)
• type Activity
• type Agent
• type Entity
• type NewActivity
• type NewAgent
• type NewEntity
• type Relationship
• type Relationships
• type SubGraph

Variables

var (
	// ErrNotFound is used when a specific Agent is requested but does not exist.
	ErrNotFound = errors.New("Not found")
	// ErrInvalidID is used when an invalid UUID is provided.
	ErrInvalidID = errors.New("ID is not in its proper form")
)

Predefined errors identify expected failure conditions.

Functions

func PrepareNewActivity

func PrepareNewActivity(newActivity *NewActivity, traceID string, now time.Time) (Activity, SubGraph)

PrepareNewActivity prepares an activity submitted through a client for storage. It preforms preparation tasks including assinging ids and annotations as well and normalization tasks that turn nested activities into a flat graph.

func PrepareNewAgent

func PrepareNewAgent(newAgent *NewAgent, traceID string, now time.Time) (Agent, SubGraph)

PrepareNewAgent prepares an agent submitted through a client for storage. It preforms preparation tasks including assinging ids and annotations as well and normalization tasks that turn nested agent into a flat graph.

func PrepareNewEntity

func PrepareNewEntity(newEntity *NewEntity, traceID string, now time.Time) (Entity, SubGraph)

PrepareNewEntity prepares an entity submitted through a client for storage. It preforms preparation tasks including assinging ids and annotations as well and normalization tasks that turn nested entity into a flat graph.

Types

type Activity

type Activity struct {
	ID                string            `json:"id"`                    // Unique identifier.
	CanonicalID       string            `json:"canonicalId,omitempty"` // Id for agent that exists outside of provly.
	Name              string            `json:"name"`                  // Human redable name of the agent.
	Kind              string            `json:"kind,omitempty"`        // A reference to the kind of agent this is.
	Annotations       map[string]string `json:"annotations"`           // Machine readable annotations
	CreatedAt         time.Time         `json:"createdAt"`             // When the agent was added.
	StartTime         time.Time         `json:"startTime"`             // The time that the experiment started.
	Duration          time.Duration     `json:"duration"`              // How long the experiment took.
	Used              []Entity          `json:"used"`                  // A list of entities that the activity used.
	WasAssociatedWith []Agent           `json:"wasAssociatedWith"`     // A list of agents the activity was associated with.
	WasInformedBy     []Activity        `json:"wasInformedBy"`         // A separate activity that informed this activity
}

Activity defines a provenance activity. It is the core concept of the provenance graph. It is the thing that agents do in order to create new entities.

type Agent

type Agent struct {
	ID              string            `json:"id"`                        // Unique identifier.
	CanonicalID     string            `json:"canonicalId,omitempty"`     // Id for agent that exists outside of provly.
	Name            string            `json:"name"`                      // Human redable name of the agent.
	Kind            string            `json:"kind,omitempty"`            // A reference to the kind of agent this is.
	Annotations     map[string]string `json:"annotations"`               // Machine readable annotations
	CreatedAt       time.Time         `json:"createdAt"`                 // When the agent was added.
	Hash            string            `json:"hash,omitempty"`            // Hash of the asset to ensure integrity, this is probably only realistic for software.
	ActedOnBehalfOf *Agent            `json:"actedOnBehalfOf,omitempty"` // An agent on which this agent was acting on behalf of.
}

Agent is an person, organization or software.

type Entity

type Entity struct {
	ID              string            `json:"id"`                    // Unique identifier.
	CanonicalID     string            `json:"canonicalId,omitempty"` // Id for agent that exists outside of provly.
	Name            string            `json:"name"`                  // Human redable name of the agent.
	Kind            string            `json:"kind,omitempty"`        // A reference to the kind of agent this is.
	Annotations     map[string]string `json:"annotations"`           // Machine readable annotations
	CreatedAt       time.Time         `json:"createdAt"`             // When the agent was added.
	Hash            string            `json:"hash,omitempty"`        // A hash of the entity.
	WasDerivedFrom  *Entity           `json:"wasDerivedFrom"`        // An entity this entity was derived from.
	WasGeneratedBy  *Activity         `json:"wasGeneratedBy"`        // The activity that generated this entity.
	WasAttributedTo []Agent           `json:"wasAttributedTo"`       // The agents this entity was attributed to.
}

Entity is a core provenance type.

type NewActivity

type NewActivity struct {
	ID                string            `json:"id,omitempty" validate:"omitempty,uuid"`
	CanonicalID       string            `json:"canonicalId,omitempty" validate:"omitempty,uuid"`
	Name              string            `json:"name" validate:"required"`
	Annotations       map[string]string `json:"annotations" validate:"-"`
	Kind              string            `json:"kind" validate:"urn_rfc2141,required"`
	StartTime         time.Time         `json:"startTime" validate:"-"`
	Duration          time.Duration     `json:"duration" validate:"-"`
	Used              []NewEntity       `json:"used" validate:"omitempty,dive"`
	WasAssociatedWith []NewAgent        `json:"wasAssociatedWith" validate:"omitempty,dive"`
	WasInformedBy     []NewActivity     `json:"wasInformedBy" validate:"omitempty,dive"`
}

NewActivity is what we require from the client when adding an activity

type NewAgent

type NewAgent struct {
	ID              string            `json:"id,omitempty" validate:"omitempty,uuid"`
	CanonicalID     string            `json:"canonicalId,omitempty" validate:"omitempty,uuid"`
	Name            string            `json:"name" validate:"required"`
	Annotations     map[string]string `json:"annotations" validate:"-"`
	Kind            string            `json:"kind" validate:"urn_rfc2141,required"`
	Hash            string            `json:"hash,omitempty" validate:"omitempty,base64"`
	ActedOnBehalfOf *NewAgent         `json:"actedOnBehalfOf,omitempty" validate:"omitempty,dive"`
}

NewAgent is what we require from clients when adding a Agent.

type NewEntity

type NewEntity struct {
	ID              string            `json:"id,omitempty" validate:"omitempty,uuid"`
	CanonicalID     string            `json:"canonicalId,omitempty" validate:"omitempty,uuid"`
	Name            string            `json:"name" validate:"required"`
	Annotations     map[string]string `json:"annotations" validate:"-"`
	Kind            string            `json:"kind" validate:"urn_rfc2141,required"`
	Hash            string            `json:"hash,omitempty" validate:"omitempty,base64"`
	WasDerivedFrom  *NewEntity        `json:"wasDerivedFrom" validate:"omitempty,dive"`
	WasGeneratedBy  *NewActivity      `json:"wasGeneratedBy" validate:"omitempty,dive"`
	WasAttributedTo []NewAgent        `json:"wasAttributedTo" validate:"omitempty,dive"`
}

NewEntity is what is expected of a client in order to create a new entity

type Relationship

type Relationship string

Relationship is a enumeration of all relationships defined in the provenance graph.

const (
	// ActedOnBehalfOf is a relationship between two agents.
	ActedOnBehalfOf Relationship = "actedOnBehalfOf"
	// Used is a relationship in which an activity uses an entity.
	Used Relationship = "used"
	// WasAssociatedWith is a relationship in which an activity is associated with an agent.
	WasAssociatedWith Relationship = "wasAssociatedWith"
	// WasAttributedTo is a relationship in which an entity is attributed to an agent.
	WasAttributedTo Relationship = "wasAttributedTo"
	// WasGeneratedBy is a relationship in which an entity was generated by an activity.
	WasGeneratedBy Relationship = "wasGeneratedBy"
	// WasDerivedFrom is a relationship in which an entity was derived from another entity.
	WasDerivedFrom Relationship = "wasDerivedFrom"
	// WasInformedBy is a relationship in which an activity informs another activiy.
	WasInformedBy Relationship = "wasInformedBy"
)

type Relationships

type Relationships struct {
	From        string            // The source entity.
	To          string            // The destination entity.
	Annotations map[string]string // Machine readable annotations.
	CreatedAt   time.Time         // When the agent was added.

	RelationshipType Relationship // The type of relationship this is.
}

Relationships is an abstraction on all provenance relationships. The from, to, annotations, and createdAt fields are part of the application while the RelationType field defines what relationship it is.

type SubGraph

type SubGraph struct {
	// Entities
	Activities []Activity
	Entities   []Entity
	Agents     []Agent

	// Relationships
	Relationships []Relationships
}

SubGraph is a normalized list of all the entities and relationships in a provenance subgraph.