-
Notifications
You must be signed in to change notification settings - Fork 19
/
topic.go
251 lines (168 loc) · 7.52 KB
/
topic.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
// SPDX-FileCopyrightText: 2022 SAP SE or an SAP affiliate company and Open Component Model contributors.
//
// SPDX-License-Identifier: Apache-2.0
package descriptor
import (
"github.com/spf13/cobra"
"github.com/open-component-model/ocm/v2/pkg/contexts/ocm/accessmethods/options"
)
func New() *cobra.Command {
return &cobra.Command{
Use: "descriptor",
Short: "Plugin Descriptor Format Description",
Example: `
{
"version": "v1",
"pluginName": "test",
"pluginVersion": "v1",
"shortDescription": "a test plugin",
"description": "a test plugin with access method test",
"accessMethods": [
{
"description": "",
"name": "test",
"shortDescription": "test access"
},
{
"description": "",
"name": "test",
"shortDescription": "test access",
"version": "v1"
}
],
"uploaders": [
{
"constraints": [
{
"artifactType": "TestArtifact"
}
],
"name": "testuploader"
}
]
}
`,
Long: `
The plugin descriptor describes the capabilities of a plugin. It uses the
following fields:
- **<code>version</code>** *string*
The format version of the information descriptor. The actually supported
version is <code>v1</code>
- **<code>pluginName</code>** *string*
The name of the plugin, it must correspond to the file name of the executable.
- **<code>pluginVersion</code>** *string*
The version of the plugin. This is just an information field not used by the
library
- **<code>shortDescription</code>** *string*
A short description shown in the plugin overview provided by the command
<code>ocm get plugins</code>.
- **<code>description</code>** *string*
A description explaining the capabilities of the plugin
- **<code>accessMethods</code>** *[]AccessMethodDescriptor*
The list of access methods versions provided by this plugin.
This feature is already used to establish new access types, if
the plugins are registered at an OCM context.
- **<code>uploaders</code>** *[]UploaderDescriptor*
The list of supported uploaders. Uploaders will be used in a future
version to describe foreign repository targets for local blobs
of dedicated types imported into an OCM registry.
- **<code>downloaders</code>** *[]DownloaderDescriptor*
The list of supported downloaders. Downloaders will be used by the
CLI download command to provide downloaded artifacts in a filesystem format
applicable to the type specific tools, regatdless of the format it is stored
as blob in a component version. Therefore, they can be registered for
combination of artifact type and optional mime type (describing the actually
used blob format).
- **<code>actions</code>** *[]ActionDescriptor*
The list of supported actions. Actions are defined by the used OCM
library to externalize element or element type related tasks, which
require dedicated environment specific actions.
For example, the creation of OCI repositories before an artifact upload.
#### Access Method Descriptor
An access method descriptor describes a dedicated supported access method.
It uses the following fields:
- **<code>name</code>** *string*
The name of the access method.
- **<code>version</code>** *string*
The version of the access method (default is <code>v1</code>).
- **<code>description</code>** *string*
The description of the dedicated kind of access method. It must
only be reported for one supported version.
- **<code>format</code>** *string*
The description of the dedicated format version of an access method.
- **<code>options</code>** *[]Option]*
Optional list of options provided for the command <code>ocm add resources</code>.
If options are given, the plugin must support the command <CMD>plugin accessmethod compose</CMD>.
An option is defined by the following fields:
- **<code>name</code>** *string*
This required field describe the name of the option. THis might be
the name of a preconfigured option, or a new one.
- **<code>type</code>** *string*
This optional field describe the intended type for a new option.
- **<code>description</code>** *string*
This optional field is as description for a newly created option.
If possible, predefined standard options should be used. In such a case
only the <code>name</code> field should be defined for
an option. If required, new options can be defined by additionally specifying
a type and a description. New options should be used very carefully. The
chosen names MUST not conflict with names provided by other plugins. Therefore
it is highly recommended to use use names prefixed by the plugin name.
` + options.DefaultRegistry.Usage() + `
#### Uploader Descriptor
The descriptor for an uploader has the following fields:
- **<code>name</code>** *string*
The name of the uploader.
- **<code>description</code>** *string*
The description of the uploader
- **<code>constraints</code>** *[]Constraint*
The list of constraints the uploader is usable for. A constraint is described
by two fields:
- **<code>artifactType</code>** *string*
Restrict the usage to a dedicated artifact type.
- **<code>mediaType</code>** *string*
Restrict the usage to a dedicated media type of the artifact blob.
- **<code>contextType</code>** *string*
Restrict the usage to a dedicated implementation backend technology.
If specified, the attribute <code>repositoryType</code> must be set, also.
- **<code>repositoryType</code>** *string*
Restrict the usage to a dedicated implementation of the backend technology.
If specified, the attribute <code>contextType</code> must be set, also.
#### Downloader Descriptor
The descriptor for a downloader has the following fields:
- **<code>name</code>** *string*
The name of the uploader.
- **<code>description</code>** *string*
The description of the uploader
- **<code>constraints</code>** *[]DownloadConstraint*
The list of constraints the downloader is usable for. A constraint is described
by two fields:
- **<code>artifactType</code>** *string*
Restrict the usage to a dedicated artifact type.
- **<code>mediaType</code>** *string* (optional)
Restrict the usage to a dedicated media type of the artifact blob.
#### Action Descriptor
The descriptor for an action has the following fields:
- **<code>name</code>** *string*
The name of the action (for example <code>oci.repository.prepare</code>).
- **<code>versions</code>** *[]string*
A list of accepted specification versions of the action.
The used version is negotiated between the caller and the plugin
by selecting the latest version supported by both parties.
- **<code>description</code>** *string* (optional)
A short description of the provided tasks done by this action.
- **<code>defaultSelectors</code>** *[]string* (optional)
A list of selectors, for which this action implementation is automatically
be registered when the plugin is loaded. The selector syntax depends on
the action type. (For example, the hostname (pattern) for the action
<code>oci.repository.prepare</code>). The selectors are eiker directly matched
with action requests or used as regular expression.
- **<code>consumerType</code>** *string* (optional)
By default, the action gets access to the credentials provided for the
element the action should work on. But it might be, that other credentials
are required to fulfill its task. Therefore, the action can request a dedicated
consumer type used to lookup the credentials. The consumer attributes are
derived from the the action specification and cannot be influenced by the
plugin.
`,
}
}