From d74961db65436716ac2b4840d7d89cf2cfa7e08b Mon Sep 17 00:00:00 2001 From: Uwe Krueger Date: Mon, 28 Oct 2024 14:59:11 +0100 Subject: [PATCH] docu + review comments --- api/ocm/plugin/descriptor/descriptor.go | 13 +++++++++--- api/ocm/plugin/internal/transfer.go | 12 ++++++++++- api/ocm/plugin/ppi/interface.go | 21 +++++++++++++++++++ api/ocm/plugin/ppi/utils.go | 4 ++++ api/tech/access.go | 6 +++--- .../transferhandlers/demo_test.go | 10 +++++---- 6 files changed, 55 insertions(+), 11 deletions(-) diff --git a/api/ocm/plugin/descriptor/descriptor.go b/api/ocm/plugin/descriptor/descriptor.go index 40bcf98112..b6e08d5ed6 100644 --- a/api/ocm/plugin/descriptor/descriptor.go +++ b/api/ocm/plugin/descriptor/descriptor.go @@ -259,9 +259,16 @@ func (d TransferHandlerDescriptor) GetQuestion(name string) *QuestionDescriptor } type QuestionDescriptor struct { - Question string `json:"question"` - Description string `json:"description,omitempty"` - Labels *[]string `json:"labels,omitempty"` + // Question is the name of the question the plugin can answer. + // Possible types and their meaning is described by the + // variable common.TransferHandlerQuestions. + Question string `json:"question"` + Description string `json:"description,omitempty"` + // Labels described the list of labels passed to the + // plugin if they exist. If not specified all labels + // are transferred, if an empty list is specified no + // labels are transferred to the plugin command. + Labels *[]string `json:"labels,omitempty"` } //////////////////////////////////////////////////////////////////////////////// diff --git a/api/ocm/plugin/internal/transfer.go b/api/ocm/plugin/internal/transfer.go index 76dc3cd5c1..f85ace3db7 100644 --- a/api/ocm/plugin/internal/transfer.go +++ b/api/ocm/plugin/internal/transfer.go @@ -52,22 +52,30 @@ type Resolution struct { RepositorySpec *ocm.GenericRepositorySpec `json:"repository,omitempty"` // TransferHandler is the handler identity according to the transfer handler // name scheme. - TransferHandler string `json:"transferHandler,omitempty"` + TransferHandler string `json:"transferHandler,omitempty"` + // TransferOptions may describe modified options used for sub-sequent + // transfers. TransferOptions *TransferOptions `json:"transferOptions,omitempty"` } +// DecisionRequestResult is the structure of the answer +// the plugin has to return for a question. type DecisionRequestResult struct { Error string `json:"error,omitempty"` Decision bool `json:"decision"` Resolution *Resolution `json:"resolution,omitempty"` } +// ComponentVersionQuestion describes the question arguments +// given for a component version related question. type ComponentVersionQuestion struct { Source SourceComponentVersion `json:"source"` Target TargetRepositorySpec `json:"target"` Options TransferOptions `json:"options"` } +// ComponentReferenceQuestion describes the question arguments +// given for a component version reference related question. type ComponentReferenceQuestion struct { Source SourceComponentVersion `json:"source"` Target TargetRepositorySpec `json:"target"` @@ -84,6 +92,8 @@ type Artifact struct { AccessInfo UniformAccessSpecInfo `json:"accessInfo"` } +// ArtifactQuestion describes the question arguments +// given for an artifact related question. type ArtifactQuestion struct { Source SourceComponentVersion `json:"source"` Artifact Artifact `json:"artifact"` diff --git a/api/ocm/plugin/ppi/interface.go b/api/ocm/plugin/ppi/interface.go index 55e0a2cd89..4e843bee60 100644 --- a/api/ocm/plugin/ppi/interface.go +++ b/api/ocm/plugin/ppi/interface.go @@ -220,17 +220,38 @@ type Command interface { Command() *cobra.Command } +// TransferHandler is the support interface +// for implementing a transfer handler for the plugin support +// library. +// There is a standard implementation NewTransferHandler. type TransferHandler interface { GetName() string GetDescription() string GetQuestions() []DecisionHandler } +// DecisionHandler is the support interface for implementing +// the answer to a question used for the TransferHandler. +// A base implementation providing the non-functional attributues +// cane be obtained by NewDecisionHandlerBase. type DecisionHandler interface { + // GetQuestion returns the name of the question answered by this handler + // (see common.TransferHandlerQuestions). GetQuestion() string + GetDescription() string + // GetLabels returns the list of labels, which should be passed + // to the transfer handler. If nothing is specified all labels + // are transferred, if an empty list is given no label is handed over + // to the plugin command. GetLabels() *[]string + // DecideOn implements the calculation of the answer to + // the question.The given question contains the arguments for + // the questions. There are three kinds of arguments: + // ArtifactQuestion, ComponentVersionQuestion and ComponentReferenceQuestion. + // TransferHandlerQuestions maps the question name to the used + // argument type. DecideOn(p Plugin, question interface{}) (bool, error) } diff --git a/api/ocm/plugin/ppi/utils.go b/api/ocm/plugin/ppi/utils.go index 7ce93cb768..72808e55c1 100644 --- a/api/ocm/plugin/ppi/utils.go +++ b/api/ocm/plugin/ppi/utils.go @@ -158,6 +158,10 @@ func (t *transferHandler) RegisterDecision(h DecisionHandler) error { return nil } +// DecisionHandlerBase provides access to the +// non-functional attributes of a DecisionHandler. +// It can be created with NewDecisionHandlerBase and +// embedded into the final DecisionHandler implementation. type DecisionHandlerBase struct { question string description string diff --git a/api/tech/access.go b/api/tech/access.go index ef351abdd5..0da2e8577c 100644 --- a/api/tech/access.go +++ b/api/tech/access.go @@ -1,11 +1,11 @@ package tech // UniformAccessSpecInfo describes a rough uniform specification for -// an access location or an accessed object. It not necessarily -// provided the exact access information required to technically +// an access location or an accessed object. It does not necessarily +// provide the exact access information required to technically // access the object, but just some general information usable // independently of the particular technical access specification -// to figure aut some general information in a formal way about the access. +// to figure out some general information in a formal way about the access. type UniformAccessSpecInfo struct { Kind string `json:"kind"` Host string `json:"host,omitempty"` diff --git a/cmds/transferplugin/transferhandlers/demo_test.go b/cmds/transferplugin/transferhandlers/demo_test.go index 5ad8d7e31b..64eec919e6 100644 --- a/cmds/transferplugin/transferhandlers/demo_test.go +++ b/cmds/transferplugin/transferhandlers/demo_test.go @@ -4,12 +4,14 @@ import ( "bytes" "encoding/json" - "github.com/mandelsoft/goutils/sliceutils" . "github.com/mandelsoft/goutils/testutils" - "github.com/mandelsoft/vfs/pkg/osfs" - "github.com/mandelsoft/vfs/pkg/vfs" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" + + "github.com/mandelsoft/goutils/sliceutils" + "github.com/mandelsoft/vfs/pkg/osfs" + "github.com/mandelsoft/vfs/pkg/vfs" + "ocm.software/ocm/api/ocm" metav1 "ocm.software/ocm/api/ocm/compdesc/meta/v1" v2 "ocm.software/ocm/api/ocm/compdesc/versions/v2" @@ -23,7 +25,7 @@ import ( ) var _ = Describe("Test Environment", func() { - It("", func() { + It("runs a demo question", func() { var stdout bytes.Buffer var stderr bytes.Buffer