or
or
By clicking below, you agree to our terms of service.
New to HackMD? Sign up
Syntax | Example | Reference | |
---|---|---|---|
# Header | Header | 基本排版 | |
- Unordered List |
|
||
1. Ordered List |
|
||
- [ ] Todo List |
|
||
> Blockquote | Blockquote |
||
**Bold font** | Bold font | ||
*Italics font* | Italics font | ||
~~Strikethrough~~ | |||
19^th^ | 19th | ||
H~2~O | H2O | ||
++Inserted text++ | Inserted text | ||
==Marked text== | Marked text | ||
[link text](https:// "title") | Link | ||
![image alt](https:// "title") | Image | ||
`Code` | Code |
在筆記中貼入程式碼 | |
```javascript var i = 0; ``` |
|
||
:smile: | ![]() |
Emoji list | |
{%youtube youtube_id %} | Externals | ||
$L^aT_eX$ | LaTeX | ||
:::info This is a alert area. ::: |
This is a alert area. |
On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?
Please give us some advice and help us improve HackMD.
Syncing
xxxxxxxxxx
Hora Referrer Store Specification
tags:
Hora
Overview
A referrer store in the framework is a component that can store and distribute OCI artifacts with the ability to discover reference types for a subject. It provides the following capabilities
This document proposes a generic plugin-based solution for integrating different stores into the framework.
Terminology
The following terms will be used throughout the document
The following sections of the document aims to specify the interface between "framework" and "plugins"
Specification
The store specification defines
Section1 : Store Configuration format
The framework can be configured with a set of parameters that are used by both the framework and plugins. When a specific plugin is executed, its corresponding parameters will be passed as an execution configuration to the plugin. The framework MAY support dynamic updates to the configuration as needed and hence it is recommended for the plugins to not consider this configuration as static and always use the config passed by the framework for execution.
Store Configuration format
The store configuration can be [TBD] YAML/JSON with the following properties
Plugin Configuration objects
The following are the keys used to describe configuration of individual plugins.
Any other fields specified for a plugin other than the above mentioned are considered as opaque. The framework MUST preserve unknown fields and pass through these fields to the plugins at the time of execution. Plugins may define additional fields that they accept and may generate an error if called with unknown fields.
Example store configuration
Section2 : Store Interface
The framework defines an interface for all the capabilities provided by a store.
An interace defined in
golang
:Name
The method is used to get the name of the store.
ListReferrers
This method is used to query all the referrers that are linked to a subject that is identified by a reference. The result will include the list of references and a continution token to support pagination.
GetBlobContent
[TBD] handle large objects through streaming?
This method is used to fetch the contents of a blob that is contained within the repository of the subject. The blob is identified by the given digest.
GetReferenceManifest
This method is used to fetch the contents of an artifact manifest that is identified by a reference descriptor. This reference descriptor is a referrer to the given subject.
Section 3 : Plugin Based Store
The framework MUST provide a reference implementation of the store interface using the plugin architecture It will execute the configured plugins to implement the methods of the interface.
The rest of the sections of the document defines the protocol for executing the plugins to implement the different methods of the store interface.
Section 4: Plugin Execution Protocol
The protocol is based on the execution of binaries invoked by the framework. The framework passes parameters to the plugin via environment variables and configuration. The configuration is supplied via
stdin
. The plugin returns the result onstdout
on success, or an error onstderr
if the verification fails. Configuration and results are encoded using JSON format.There are two types of inputs that are passed to the plugin. They are parameters which define invokation specific settings and the other is configuration that includes verifier and store configuration settings.
Parameters
Execution parameters are passed to the plugins via OS environment variables. The parameters that are passed to a store are defined below
LISTREFERRERS
,GETBLOB
,GETREFMANIFEST
{DNS/IP}/{Repository}:[name|digest]
version
field of the store configuration.Operations & Parameters
The store specification defines 3 operations
LISTREFERRERS
,GETBLOB
,GETREFMANIFEST
The operation type is passed to the plugin via the HORA_STORE_COMMAND environemnt variable.LISTREFERRERS
: Get the list of referrers to the given subject. The arguments that are passed to this operation as part of HORA_STORE_ARGS arenextToken
: (string) The continuation token obtained from the previousLISTREFERRERS
oeprationartifactTypes
: (string) Comma separated list of artifact types that are used for filtering the referrers.GETBLOB
: The arguments that are passed to this oepration as part of HORA_STORE_ARGS aredigest
: (string) The digest of the blob that has to be retrieved.GETREFMANIFEST
: The arguments that are passed to this oepration as part of HORA_STORE_ARGS aredigest
: (string) The digest of the artifact manifest that has to be retrieved.Execution Configuration
When a plugin is registered using the configuration, the framework interprets the configuration per plugin and transforms it to a format that is expected by the plugin. This section describes the transformations made by the framework before the configuration is passed to the plugin.
The execution configuration for a plugin invocation is encoded in JSON. It will contain the plugin configuration that is provided by the user, primarily unchanged except for the specified additions
The execution configuration provided by the framework will contain the following fields.
config
: A JSON object representing the plugin configuration provided as part of registration with the framework and passed unchanged.Section 5: Operations & Result Types
Plugins can return either a Success or Error result type.
Success
The store specification defines 3 operations
LISTREFERRERS
,GETBLOB
,GETREFMANIFEST
The success result types for each of these operations are defined belowLISTREFERRERS
: Get the list of referrers to the given subject. The result JSON returned for this operation has the following propertiesreferrers
: (list) A list of referrers to the given subject identified by their descriptorsnextToken
: (string) The continuation token that SHOULD be used to get the next page of referrers.GETBLOB
: The content of the blob is returned as byte array viastdout
GETREFMANIFEST
: The content of the reference manifest is returned as byte array via ```stdout``Error
Plugins should output a JSON object with the following properties if they encounter an error
code
: A numeric error code as described belowmsg
: A short message describing the errordetails
: More details describing the error.[TODO] Add the error codes after the implementation
Section 5: Plugin Implementation
The framework MAY provide libraries that can provide skeletons for writing plugins. These libraries can scaffold the parameter and configuration parsing and transformation and can define methods that the plugin writers can override for the implementation. These libraries also should catch any exceptions retruned from the plugins and return a proper error result to the framework. A simple CLI for example
hora plugin store add mystore
to create a stub for a plugin using these libraries MAY be provided by the framework.Appendix : Examples
A example protocol sequence for a
LISTREFERRERS
operation is given belowregistry.wabbit-networks.io:5000/net-monitor:signed@sha256:a0fc570a245b09ed752c42d600ee3bb5b4f77bbd70d8898780b7ab43454530eb
will be used to query for its referrers of typeapplication/vnd.cncf.notary.v2
.ociregistry
with the following environment variablesLISTREFERRERS
registry.wabbit-networks.io:5000/net-monitor:signed@sha256:a0fc570a245b09ed752c42d600ee3bb5b4f77bbd70d8898780b7ab43454530eb
1.0.0
artifactTypes:application/vnd.cncf.notary.v2
ociregistry
queries the registry using the provided configuration and returns a following JSON result