design

Documentation

Overview

Package design is the single source of truth of Enduro's API. It uses the Goa design language (https://goa.design) which is a Go DSL.

We describe multiple services (package) which map to resources in REST or service declarations in gRPC. Services define their own methods, errors, etc...

UUID attributes

Use AttributeUUID or TypedAttributeUUID to declare UUID attributes.

These attributes produce consistent example UUIDs.

Index

• Variables
• func AttributeUUID(name, desc string)
• func PaginatedCollectionOf(v interface{}, adsl ...func()) interface{}
• func TypedAttributeUUID(name, desc string)

Variables

var AMSSConfig = Type("AMSSConfig", func() {
	ConvertTo(types.AMSSConfig{})

	Attribute("api_key", String)
	Attribute("url", String)
	Attribute("username", String)

	Required("api_key", "url", "username")
})

var AddLocationResult = Type("AddLocationResult", func() {
	Attribute("uuid", String)
	Required("uuid")
})

var EnumLocationPurpose = func() {
	Enum("unspecified", "aip_store")
}

var EnumLocationSource = func() {
	Enum("unspecified", "minio", "sftp", "amss")
}

var EnumPackageStatus = func() {
	Enum(enums.PackageStatusInterfaces()...)
}

var EnumPreservationActionStatus = func() {
	Enum(enums.PreservationActionStatusInterfaces()...)
}

var EnumPreservationActionType = func() {
	Enum(enums.PreservationActionTypeInterfaces()...)
}

var EnumPreservationTaskStatus = func() {
	Enum(enums.PreservationTaskStatusInterfaces()...)
}

var EnumStoragePackageStatus = func() {
	Enum("unspecified", "in_review", "rejected", "stored", "moving")
}

var JWTAuth = JWTSecurity("jwt", func() {
	Description("Secures endpoint by requiring a valid JWT token.")
	Scope("package:list")
	Scope("package:listActions")
	Scope("package:move")
	Scope("package:read")
	Scope("package:review")
	Scope("package:upload")
	Scope("storage:location:create")
	Scope("storage:location:list")
	Scope("storage:location:listPackages")
	Scope("storage:location:read")
	Scope("storage:package:create")
	Scope("storage:package:download")
	Scope("storage:package:move")
	Scope("storage:package:read")
	Scope("storage:package:review")
	Scope("storage:package:submit")
})

var Location = ResultType("application/vnd.enduro.storage-location", func() {
	Description("A Location describes a location retrieved by the storage service.")
	TypeName("Location")

	Attributes(func() {
		Attribute("name", String, "Name of location")
		Attribute("description", String, "Description of the location")
		Attribute("source", String, "Data source of the location", func() {
			EnumLocationSource()
			Default("unspecified")
		})
		Attribute("purpose", String, "Purpose of the location", func() {
			EnumLocationPurpose()
			Default("unspecified")
		})
		Attribute("uuid", String, func() {
			Meta("struct:field:type", "uuid.UUID", "github.com/google/uuid")
		})
		OneOf("config", func() {
			Attribute("amss", AMSSConfig)
			Attribute("s3", S3Config)
			Attribute("sftp", SFTPConfig)
			Attribute("url", URLConfig)
		})
		Attribute("created_at", String, "Creation datetime", func() {
			Format(FormatDateTime)
		})
		Required("name", "source", "purpose", "uuid", "created_at")
	})

	View("default", func() {
		Attribute("name")
		Attribute("description")
		Attribute("source")
		Attribute("purpose")
		Attribute("uuid")
		Attribute("created_at")
	})
})

var LocationNotFound = Type("LocationNotFound", func() {
	Description("Storage location not found.")
	TypeName("LocationNotFound")
	Attribute("message", String, "Message of error", func() {
		Meta("struct:error:message")
	})
	Attribute("uuid", String, func() {
		Meta("struct:field:type", "uuid.UUID", "github.com/google/uuid")
	})
	Required("message", "uuid")
})

var MonitorEvent = Type("MonitorEvent", func() {
	OneOf("event", func() {
		Attribute(
			"monitor_ping_event",
			MonitorPingEvent,
		)
		Attribute(
			"package_created_event",
			PackageCreatedEvent,
		)
		Attribute(
			"package_updated_event",
			PackageUpdatedEvent,
		)
		Attribute(
			"package_status_updated_event",
			PackageStatusUpdatedEvent,
		)
		Attribute(
			"package_location_updated_event",
			PackageLocationUpdatedEvent,
		)
		Attribute(
			"preservation_action_created_event",
			PreservationActionCreatedEvent,
		)
		Attribute(
			"preservation_action_updated_event",
			PreservationActionUpdatedEvent,
		)
		Attribute(
			"preservation_task_created_event",
			PreservationTaskCreatedEvent,
		)
		Attribute(
			"preservation_task_updated_event",
			PreservationTaskUpdatedEvent,
		)
	})
})

var MonitorPingEvent = Type("MonitorPingEvent", func() {
	Attribute("message", String)

	Meta("type:generate:force")
	Meta("openapi:typename", "MonitorPingEvent")
})

var MoveStatusResult = Type("MoveStatusResult", func() {
	Attribute("done", Boolean)
	Required("done")
})

var PackageCreatedEvent = Type("PackageCreatedEvent", func() {
	Attribute("id", UInt, "Identifier of package")
	Attribute("item", StoredPackage, func() { View("default") })
	Required("id", "item")

	Meta("type:generate:force")
	Meta("openapi:typename", "PackageCreatedEvent")
})

var PackageList = ResultType("application/vnd.enduro.packages", func() {
	Attribute("items", CollectionOf(StoredPackage))
	Attribute("page", Page)
	Required("items", "page")
})

var PackageLocationUpdatedEvent = Type("PackageLocationUpdatedEvent", func() {
	Attribute("id", UInt, "Identifier of package")
	TypedAttributeUUID("location_id", "Identifier of storage location")
	Required("id", "location_id")

	Meta("type:generate:force")
	Meta("openapi:typename", "PackageLocationUpdatedEvent")
})

var PackageNotFound = Type("PackageNotFound", func() {
	Description("Package not found.")
	TypeName("PackageNotFound")
	Attribute("message", String, "Message of error", func() {
		Meta("struct:error:message")
	})
	Attribute("id", UInt, "Identifier of missing package")
	Required("message", "id")
})

var PackageStatusUpdatedEvent = Type("PackageStatusUpdatedEvent", func() {
	Attribute("id", UInt, "Identifier of package")
	Attribute("status", String, func() {
		EnumPackageStatus()
	})
	Required("id", "status")

	Meta("type:generate:force")
	Meta("openapi:typename", "PackageStatusUpdatedEvent")
})

var PackageUpdatedEvent = Type("PackageUpdatedEvent", func() {
	Attribute("id", UInt, "Identifier of package")
	Attribute("item", StoredPackage, func() { View("default") })
	Required("id", "item")

	Meta("type:generate:force")
	Meta("openapi:typename", "PackageUpdatedEvent")
})

var Package_ = Type("Package", func() {
	Description("Package describes a package to be stored.")
	Attribute("name", String, "Name of the package")
	TypedAttributeUUID("location_id", "Identifier of storage location")
	Attribute("status", String, "Status of the package", func() {
		EnumPackageStatus()
		Default(enums.PackageStatusNew.String())
	})
	AttributeUUID("workflow_id", "Identifier of processing workflow")
	AttributeUUID("run_id", "Identifier of latest processing workflow run")
	AttributeUUID("aip_id", "Identifier of AIP")
	Attribute("created_at", String, "Creation datetime", func() {
		Format(FormatDateTime)
	})
	Attribute("started_at", String, "Start datetime", func() {
		Format(FormatDateTime)
	})
	Attribute("completed_at", String, "Completion datetime", func() {
		Format(FormatDateTime)
	})
	Required("id", "status", "created_at")
})

var Page = dsl.ResultType("application/vnd.enduro.page", func() {
	dsl.Description("Page represents a subset of search results.")
	dsl.Attribute("limit", dsl.Int, "Maximum items per page")
	dsl.Attribute("offset", dsl.Int, "Offset from first result to start of page")
	dsl.Attribute("total", dsl.Int, "Total result count before paging")
	dsl.Required("limit", "offset", "total")
})

var PreservationAction = ResultType("application/vnd.enduro.package-preservation-action", func() {
	Description("PreservationAction describes a preservation action.")
	Attributes(func() {
		Attribute("id", UInt)
		Attribute("workflow_id", String)
		Attribute("type", String, func() {
			EnumPreservationActionType()
		})
		Attribute("status", String, func() {
			EnumPreservationActionStatus()
		})
		Attribute("started_at", String, func() {
			Format(FormatDateTime)
		})
		Attribute("completed_at", String, func() {
			Format(FormatDateTime)
		})
		Attribute("tasks", CollectionOf(PreservationTask))
		Attribute("package_id", UInt)
	})
	View("simple", func() {
		Attribute("id")
		Attribute("workflow_id")
		Attribute("type")
		Attribute("status")
		Attribute("started_at")
		Attribute("completed_at")
		Attribute("package_id")
	})
	Required("id", "workflow_id", "type", "status", "started_at")
})

var PreservationActionCreatedEvent = Type("PreservationActionCreatedEvent", func() {
	Attribute("id", UInt, "Identifier of preservation action")
	Attribute("item", PreservationAction, func() {
		View("simple")
	})
	Required("id", "item")

	Meta("type:generate:force")
	Meta("openapi:typename", "PreservationActionCreatedEvent")
})

var PreservationActionUpdatedEvent = Type("PreservationActionUpdatedEvent", func() {
	Attribute("id", UInt, "Identifier of preservation action")
	Attribute("item", PreservationAction, func() {
		View("simple")
	})
	Required("id", "item")

	Meta("type:generate:force")
	Meta("openapi:typename", "PreservationActionUpdatedEvent")
})

var PreservationActions = ResultType("application/vnd.enduro.package-preservation-actions", func() {
	Description("PreservationActions describes the preservation actions of a package.")
	Attributes(func() {
		Attribute("actions", CollectionOf(PreservationAction))
	})
})

var PreservationTask = ResultType("application/vnd.enduro.package-preservation-task", func() {
	Description("PreservationTask describes a preservation action task.")
	Attributes(func() {
		Attribute("id", UInt)
		Attribute("task_id", String)
		Attribute("name", String)
		Attribute("status", String, func() {
			EnumPreservationTaskStatus()
		})
		Attribute("started_at", String, func() {
			Format(FormatDateTime)
		})
		Attribute("completed_at", String, func() {
			Format(FormatDateTime)
		})
		Attribute("note", String)
		Attribute("preservation_action_id", UInt)
	})
	Required("id", "task_id", "name", "status", "started_at")
})

var PreservationTaskCreatedEvent = Type("PreservationTaskCreatedEvent", func() {
	Attribute("id", UInt, "Identifier of preservation task")
	Attribute("item", PreservationTask, func() {
		View("default")
	})
	Required("id", "item")

	Meta("type:generate:force")
	Meta("openapi:typename", "PreservationTaskCreatedEvent")
})

var PreservationTaskUpdatedEvent = Type("PreservationTaskUpdatedEvent", func() {
	Attribute("id", UInt, "Identifier of preservation task")
	Attribute("item", PreservationTask, func() {
		View("default")
	})
	Required("id", "item")

	Meta("type:generate:force")
	Meta("openapi:typename", "PreservationTaskUpdatedEvent")
})

var S3Config = Type("S3Config", func() {
	ConvertTo(types.S3Config{})

	Attribute("bucket", String)
	Attribute("region", String)
	Attribute("endpoint", String)
	Attribute("path_style", Boolean)
	Attribute("profile", String)
	Attribute("key", String)
	Attribute("secret", String)
	Attribute("token", String)

	Required("bucket", "region")
})

var SFTPConfig = Type("SFTPConfig", func() {
	ConvertTo(types.SFTPConfig{})

	Attribute("address", String)
	Attribute("username", String)
	Attribute("password", String)
	Attribute("directory", String)

	Required("address", "username", "password", "directory")
})

var StoragePackage = ResultType("application/vnd.enduro.storage-package", func() {
	Description("A Package describes a package retrieved by the storage service.")
	TypeName("Package")

	Attributes(func() {
		Attribute("name", String)
		Attribute("aip_id", String, func() {
			Meta("struct:field:type", "uuid.UUID", "github.com/google/uuid")
		})
		Attribute("status", String, "Status of the package", func() {
			EnumStoragePackageStatus()
			Default("unspecified")
		})
		Attribute("object_key", String, func() {
			Meta("struct:field:type", "uuid.UUID", "github.com/google/uuid")
		})
		TypedAttributeUUID("location_id", "Identifier of storage location")
		Attribute("created_at", String, "Creation datetime", func() {
			Format(FormatDateTime)
		})
		Required("name", "aip_id", "status", "object_key", "created_at")
	})

	View("default", func() {
		Attribute("name")
		Attribute("aip_id")
		Attribute("status")
		Attribute("object_key")
		Attribute("location_id")
		Attribute("created_at")
	})
})

var StoragePackageNotFound = Type("StoragePackageNotFound", func() {
	Description("Storage package not found.")
	TypeName("PackageNotFound")
	Attribute("message", String, "Message of error", func() {
		Meta("struct:error:message")
	})
	Attribute("aip_id", String, "Identifier of missing package", func() {
		Meta("struct:field:type", "uuid.UUID", "github.com/google/uuid")
	})
	Required("message", "aip_id")
})

var StoredPackage = ResultType("application/vnd.enduro.stored-package", func() {
	Description("StoredPackage describes a package retrieved by the service.")
	Reference(Package_)
	Attributes(func() {
		Attribute("id", UInt, "Identifier of package")
		Attribute("name")
		Attribute("location_id")
		Attribute("status")
		Attribute("workflow_id")
		Attribute("run_id")
		Attribute("aip_id")
		Attribute("created_at")
		Attribute("started_at")
		Attribute("completed_at")
	})
	View("default", func() {
		Attribute("id")
		Attribute("name")
		Attribute("location_id")
		Attribute("status")
		Attribute("workflow_id")
		Attribute("run_id")
		Attribute("aip_id")
		Attribute("created_at")
		Attribute("started_at")
		Attribute("completed_at")
	})
	Required("id", "status", "created_at")
})

var SubmitResult = Type("SubmitResult", func() {
	Attribute("url", String)
	Required("url")
})

var URLConfig = Type("URLConfig", func() {
	ConvertTo(types.URLConfig{})
	Attribute("url", String)
	Required("url")
})

Functions

func AttributeUUID

func AttributeUUID(name, desc string)

AttributeUUID describes a string typed field that must be a valid UUID. The desc is a short description of the field's purpose.

AttributeUUID's example value is a deterministic UUID.

func PaginatedCollectionOf

func PaginatedCollectionOf(v interface{}, adsl ...func()) interface{}

func TypedAttributeUUID

func TypedAttributeUUID(name, desc string)

TypedAttributeUUID describes a uuid.UUID typed field. The desc is a short description of the field's purpose.

TypedAttributeUUID's example value is a deterministic UUID.