|
| 1 | +--- |
| 2 | +title: "Config types and an empty implementation" |
| 3 | +linkTitle: "Config types and an empty implementation" |
| 4 | +weight: 3 |
| 5 | +description: > |
| 6 | + Define the plugin's configuration types and a compiling, empty DeploymentPlugin. |
| 7 | +--- |
| 8 | + |
| 9 | +In this chapter you define the configuration types the plugin uses and add an empty implementation of the DeploymentPlugin interface. The methods do nothing yet, but the project compiles and the plugin starts, which gives you a foundation to fill in one method at a time. |
| 10 | + |
| 11 | +## Define the configuration types |
| 12 | + |
| 13 | +Recall the three type parameters of a `DeploymentPlugin`: `Config`, `DeployTargetConfig`, and `ApplicationConfigSpec`. The file plugin needs only one of them. |
| 14 | + |
| 15 | +- It has no plugin-wide configuration, so it uses `sdk.ConfigNone`, the SDK's type for an empty configuration, in place of a `Config` type. |
| 16 | +- It has no deploy targets, so its `DeployTargetConfig` is an empty struct. |
| 17 | +- It deploys to a directory that is chosen per application, so its application configuration holds a single `Path` field. |
| 18 | + |
| 19 | +Create `plugin.go` with the configuration types: |
| 20 | + |
| 21 | +```go |
| 22 | +package main |
| 23 | + |
| 24 | +import ( |
| 25 | + "context" |
| 26 | + |
| 27 | + sdk "github.com/pipe-cd/piped-plugin-sdk-go" |
| 28 | +) |
| 29 | + |
| 30 | +type ( |
| 31 | + // deployTargetConfig is empty because the file plugin has no deploy targets. |
| 32 | + deployTargetConfig struct{} |
| 33 | + |
| 34 | + // applicationConfig holds the per-application settings. The file plugin |
| 35 | + // deploys to a directory chosen per application, so it defines Path. |
| 36 | + applicationConfig struct { |
| 37 | + // Path is the directory the application deploys to. |
| 38 | + Path string `json:"path"` |
| 39 | + } |
| 40 | +) |
| 41 | +``` |
| 42 | + |
| 43 | +Both `context` and `sdk` are used by the implementation you add next. |
| 44 | + |
| 45 | +## Add an empty implementation |
| 46 | + |
| 47 | +Define a `plugin` type and give it a method for every method in the DeploymentPlugin interface. Each method calls `panic` for now. This lets you confirm that the method set and the signatures are correct before writing any real logic. |
| 48 | + |
| 49 | +Add the following to `plugin.go`: |
| 50 | + |
| 51 | +```go |
| 52 | +// plugin provides the DeploymentPlugin implementation for the file plugin. |
| 53 | +type plugin struct{} |
| 54 | + |
| 55 | +// Verify at compile time that plugin implements sdk.DeploymentPlugin. |
| 56 | +// A missing method or a wrong signature fails the build here. |
| 57 | +var _ sdk.DeploymentPlugin[sdk.ConfigNone, deployTargetConfig, applicationConfig] = (*plugin)(nil) |
| 58 | + |
| 59 | +func (p *plugin) FetchDefinedStages() []string { |
| 60 | + panic("unimplemented") |
| 61 | +} |
| 62 | + |
| 63 | +func (p *plugin) DetermineVersions(ctx context.Context, _ *sdk.ConfigNone, input *sdk.DetermineVersionsInput[applicationConfig]) (*sdk.DetermineVersionsResponse, error) { |
| 64 | + panic("unimplemented") |
| 65 | +} |
| 66 | + |
| 67 | +func (p *plugin) DetermineStrategy(ctx context.Context, _ *sdk.ConfigNone, input *sdk.DetermineStrategyInput[applicationConfig]) (*sdk.DetermineStrategyResponse, error) { |
| 68 | + panic("unimplemented") |
| 69 | +} |
| 70 | + |
| 71 | +func (p *plugin) BuildPipelineSyncStages(ctx context.Context, _ *sdk.ConfigNone, input *sdk.BuildPipelineSyncStagesInput) (*sdk.BuildPipelineSyncStagesResponse, error) { |
| 72 | + panic("unimplemented") |
| 73 | +} |
| 74 | + |
| 75 | +func (p *plugin) BuildQuickSyncStages(ctx context.Context, _ *sdk.ConfigNone, input *sdk.BuildQuickSyncStagesInput) (*sdk.BuildQuickSyncStagesResponse, error) { |
| 76 | + panic("unimplemented") |
| 77 | +} |
| 78 | + |
| 79 | +func (p *plugin) ExecuteStage(ctx context.Context, _ *sdk.ConfigNone, dts []*sdk.DeployTarget[deployTargetConfig], input *sdk.ExecuteStageInput[applicationConfig]) (*sdk.ExecuteStageResponse, error) { |
| 80 | + panic("unimplemented") |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +The `var _ sdk.DeploymentPlugin[...] = (*plugin)(nil)` line is a compile-time check. If a method is missing or its signature is wrong, the build fails on this line rather than somewhere less obvious. |
| 85 | + |
| 86 | +## Register the plugin |
| 87 | + |
| 88 | +Now that a plugin type exists, register it so `piped` can load it. Create `main.go`: |
| 89 | + |
| 90 | +```go |
| 91 | +package main |
| 92 | + |
| 93 | +import ( |
| 94 | + "log" |
| 95 | + |
| 96 | + sdk "github.com/pipe-cd/piped-plugin-sdk-go" |
| 97 | +) |
| 98 | + |
| 99 | +func main() { |
| 100 | + p, err := sdk.NewPlugin( |
| 101 | + "0.0.1", |
| 102 | + sdk.WithDeploymentPlugin(&plugin{}), |
| 103 | + ) |
| 104 | + if err != nil { |
| 105 | + log.Fatalln(err) |
| 106 | + } |
| 107 | + |
| 108 | + if err := p.Run(); err != nil { |
| 109 | + log.Fatalln(err) |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +`sdk.NewPlugin` creates the plugin server, `sdk.WithDeploymentPlugin` registers your implementation, and `p.Run()` starts the server. The first argument, `"0.0.1"`, is the plugin's own version. |
| 115 | + |
| 116 | +Build the project to confirm everything fits together: |
| 117 | + |
| 118 | +```bash |
| 119 | +go build ./... |
| 120 | +``` |
| 121 | + |
| 122 | +The project now compiles and the plugin starts, though every stage still panics. In the next chapter you replace the first `panic` with a real implementation of `FetchDefinedStages`. |
0 commit comments