docs: plugin concept docu #1122
Conversation
github-actions
bot
added
the
component/github-actions
| The commands and their interface are described in the [plugin reference](../../../docs/pluginreference/plugin.md). | ||
|
|
||
| Every plugin must provide the [`info`](../../../docs/pluginreference/plugin_info.md) command. It has to provide information | ||
| about the supported features as JSOn document on standard output. |
There was a problem hiding this comment.
| about the supported features as JSOn document on standard output. | |
| about the supported features as JSON document on standard output. |
| about the supported features as JSOn document on standard output. | ||
| The structure of this document is described by the descriptor type in package [`api/ocm/plugin/descriptor`](descriptor/descriptor.go) | ||
|
|
||
| Plugin are searched in a plugin folder (typically `.ocm/plugins`), This default location can be changed by the `plugincachedir` attribute. |
There was a problem hiding this comment.
| Plugin are searched in a plugin folder (typically `.ocm/plugins`), This default location can be changed by the `plugincachedir` attribute. | |
| Plugins are searched in a plugin folder (typically `.ocm/plugins`), This default location can be changed by the `plugincachedir` attribute. |
Could you add an example on how this attribute can be changed?
|
|
||
| ## Support for writing Plugins | ||
|
|
||
| To write an OCM plugin in Go, the provided [support library](ppi) can be used. |
There was a problem hiding this comment.
is this link to ppi working?
checked the relative link, thats working
There was a problem hiding this comment.
Why is this library inside the OCM core? That means that every go plugin has to compile the entirety of OCM itself while building, making the Plugins quite big.
There was a problem hiding this comment.
This go section deserves its own README.md just about the ppi and is not really part of a concept imo. Happy to hear other opinions
There was a problem hiding this comment.
The general high level overview of what a plugin is is shown, however its missing important flow charts and the technical packages are not well explained, thus making it hard for future maintainers to come back to this document to properly understand how it was envisioned.
| The ocm library supports a plugin mechanism to provide further variants | ||
| for OCM and library extension points without the need of extending and recompiling | ||
| the OCM CLI (and other applications using this library). |
There was a problem hiding this comment.
| The ocm library supports a plugin mechanism to provide further variants | |
| for OCM and library extension points without the need of extending and recompiling | |
| the OCM CLI (and other applications using this library). | |
| The OCM library supports a plugin mechanism to provide further library extension points without the need of extending and recompiling OCM (and other applications using this library). |
| - Uploaders | ||
| - Downloaders | ||
| - Actions | ||
| - Value sets (for example for routing slip entries) |
There was a problem hiding this comment.
Why do we have routing slips in OCM?
| - Actions | ||
| - Value sets (for example for routing slip entries) | ||
| - Config types | ||
| - Value Merge Handler (for example for label values in delta transports) |
There was a problem hiding this comment.
What does this mean? I am missing explanation on what these points should be able to do. Is that available somewhere else? if so we should link it here I think
| - CLI Commands (for OCM CLI) | ||
| - (transfer handlers) | ||
| - (signing tools) | ||
| - (input types for component version composition) |
There was a problem hiding this comment.
| - (input types for component version composition) | |
| - (new input types to compose component versions) |
| - Value sets (for example for routing slip entries) | ||
| - Config types | ||
| - Value Merge Handler (for example for label values in delta transports) | ||
| - CLI Commands (for OCM CLI) |
There was a problem hiding this comment.
I dont understand why we can add CLI Commands to a plugin infrastructure that is supposedly an interface of the library. To me that means the plugin system is not confined to the library, but to the entire codebase.
For me that means either that
- the whole plugin system is across the entirety of the OCM codebase
- we have 2 separate plugin systems that need to be documented separately and be detached from each other
| ### Extension Proxies | ||
|
|
||
| Regardless, whether it is a static type proxy or handler proxy, the proxy implementation keeps track of it plugin and extension name and maps | ||
| the extension point functionality to the Go interface of the plugin representation, which the calls the appropriate CLI command of the plugin executable. |
There was a problem hiding this comment.
This sentence is convoluted and basically only says:
"An Extension Proxy uses the Plugin & Extension name to call the go interface for the plugin that in turn calls the CLI command on the Plugin Executable"
Also im missing flow diagrams for this (and many other) interactions here.
| the registration handler registration feature of those extension points | ||
| to register an appropriate registration handler using the namespace prefix `plugin`. This handler evaluate sub names to determine the plugin name and extension name in this plugin to provide an extension handler implementation proxy to for ward the handler functionality to the appropriate plugin. | ||
|
|
||
| ### Extension Proxies |
There was a problem hiding this comment.
I dont understand the need for an extension proxy because that mapping should be resolvable without it imo. It isnt clear to me from the concept
|
|
||
| The proxy implementation are found in `plugin` packages below the extension point package (for example the [access method plugin proxy](../extensions/accessmethods/plugin)). | ||
|
|
||
| The registration handler registries are typically found in the extension point packages in (for example)) [registrations.go](../extensions/download/registration.go). The general registration handler registration handling is implemented in package [api/utils/registrations](../../utils/registrations). |
There was a problem hiding this comment.
registration handler registries and dynamic registrations are not covered well in this document imo and need additional explanation.
| The proxy implementation are found in `plugin` packages below the extension point package (for example the [access method plugin proxy](../extensions/accessmethods/plugin)). | ||
|
|
||
| The registration handler registries are typically found in the extension point packages in (for example)) [registrations.go](../extensions/download/registration.go). The general registration handler registration handling is implemented in package [api/utils/registrations](../../utils/registrations). | ||
| It is called registration handler registry, because it is a registry which provides a namespace to name the types of handlers. It is possible to register registration handlers for a sub namespace, which then handle the registration (and creation) of handlers for a particular extension point (for example download handler). |
There was a problem hiding this comment.
If that is really why it is called, then this is a very strange concept.
Why cant the registration be done natively on the underlying registry?
| It is called registration handler registry, because it is a registry which provides a namespace to name the types of handlers. It is possible to register registration handlers for a sub namespace, which then handle the registration (and creation) of handlers for a particular extension point (for example download handler). | ||
|
|
||
| The `command` extension point is implemented by the CLI package [cmds/ocm/commands/ocmcmds/plugins](../../../cmds/ocm/commands/ocmcmds/plugins). | ||
| Command extensions can be registered for any verb and object type name (even those not yet existing) and are automatically added to the command tree of the CLI. |
There was a problem hiding this comment.
Why do we need this?
hilmarf
added
kind/chore
What this PR does / why we need it
Provide documentation for the library's plugin concept and how it is used in the library.
Which issue(s) this PR fixes