doc(integrations): create template (#144)

Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev>

Author: migmartri

.golangci.yml

@@ -12,7 +12,6 @@ linters:
     - nakedret
     - revive
     - gosec
-    - depguard
     - asciicheck
     - whitespace
     - errorlint

app/cli/internal/action/integration_add_deptrack.go

@@ -19,8 +19,8 @@ import (
 	"context"
 
 	pb "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1"
-	deptrack "github.com/chainloop-dev/chainloop/app/controlplane/extensions/dependencytrack/v1"
-	cxpb "github.com/chainloop-dev/chainloop/app/controlplane/extensions/dependencytrack/v1/api"
+	deptrack "github.com/chainloop-dev/chainloop/app/controlplane/extensions/core/dependencytrack/v1"
+	cxpb "github.com/chainloop-dev/chainloop/app/controlplane/extensions/core/dependencytrack/v1/api"
 	"google.golang.org/protobuf/types/known/anypb"
 )
 

app/cli/internal/action/workflow_integration_attach.go

@@ -19,7 +19,7 @@ import (
 	"context"
 
 	pb "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1"
-	cxpb "github.com/chainloop-dev/chainloop/app/controlplane/extensions/dependencytrack/v1/api"
+	cxpb "github.com/chainloop-dev/chainloop/app/controlplane/extensions/core/dependencytrack/v1/api"
 	"google.golang.org/protobuf/types/known/anypb"
 )
 

app/controlplane/Makefile

@@ -11,10 +11,10 @@ api:
 	cd ./api && buf generate
 	cd ./extensions && buf generate
 
-.PHONY: api-integrations
+.PHONY: api-extensions
 # generate integrations proto bindings
-api-integrations:
-	cd ./integrations && buf generate
+api-extensions:
+	cd ./extensions && buf generate
 
 .PHONY: build
 # build
@@ -43,13 +43,13 @@ test-unit:
 # lint
 lint:
 	buf lint api
-	buf lint integrations
+	buf lint extensions
 	buf lint internal/conf
 	golangci-lint run
 
 .PHONY: generate
 # generate proto bindings, wire injectors, and ent models
-generate: api config api-integrations
+generate: api config api-extensions
 	go generate ./...
 
 .PHONY: all

app/controlplane/cmd/main.go

@@ -17,21 +17,18 @@ package main
 
 import (
 	"context"
-	"fmt"
 	"os"
 	"time"
 
 	"github.com/getsentry/sentry-go"
 	flag "github.com/spf13/pflag"
 
-	"github.com/chainloop-dev/chainloop/app/controlplane/extensions/sdk/v1"
 	"github.com/chainloop-dev/chainloop/app/controlplane/internal/biz"
 	"github.com/chainloop-dev/chainloop/app/controlplane/internal/conf"
 	"github.com/chainloop-dev/chainloop/app/controlplane/internal/server"
 	credsConfig "github.com/chainloop-dev/chainloop/internal/credentials/api/credentials/v1"
 	"github.com/chainloop-dev/chainloop/internal/servicelogger"
 
-	deptrack "github.com/chainloop-dev/chainloop/app/controlplane/extensions/dependencytrack/v1"
 	"github.com/go-kratos/kratos/v2"
 	"github.com/go-kratos/kratos/v2/config"
 	"github.com/go-kratos/kratos/v2/config/env"
@@ -127,21 +124,6 @@ func main() {
 	}
 }
 
-// Load the available third party integrations
-// In the future this code will iterate over a dynamic directory of plugins
-// and try to load them one by one
-func loadExtensions(l log.Logger) (sdk.Loaded, error) {
-	var res sdk.Loaded
-
-	var d sdk.FanOut
-	d, err := deptrack.NewIntegration(l)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load dependency track extension: %w", err)
-	}
-
-	return append(res, d), nil
-}
-
 type app struct {
 	*kratos.App
 	// Periodic job that expires unfinished attestation processes older than a given threshold

app/controlplane/cmd/wire.go

@@ -21,6 +21,7 @@
 package main
 
 import (
+	"github.com/chainloop-dev/chainloop/app/controlplane/extensions"
 	"github.com/chainloop-dev/chainloop/app/controlplane/internal/biz"
 	"github.com/chainloop-dev/chainloop/app/controlplane/internal/conf"
 	"github.com/chainloop-dev/chainloop/app/controlplane/internal/data"
@@ -48,7 +49,7 @@ func wireApp(*conf.Bootstrap, credentials.ReaderWriter, log.Logger) (*app, func(
 			serviceOpts,
 			wire.Value([]biz.CASClientOpts{}),
 			wire.FieldsOf(new(*conf.Bootstrap), "Server", "Auth", "Data", "CasServer"),
-			loadExtensions,
+			extensions.Load,
 			dispatcher.New,
 			newApp,
 		),

app/controlplane/cmd/wire_gen.go

@@ -0,0 +1,52 @@
+# Chainloop Extensions
+
+Chainloop extensions are a way to extend the functionality of the Chainloop. 
+
+Currently we only support one type, fan-out extensions. FanOut extensions implement logic that will get executed when attestations or materials are received, 
+
+## Anatomy of a FanOut Extension
+
+### Lifecycle
+
+An fanOut extension goes through 4 different stages. Loading, Registration, Attachment and Execution
+
+#### Loading
+
+Loading is when the extension gets enabled in the Chainloop Control plane. This is implemented via the extension constructor. At this time is when you, as a developer, can configure the identity of the extension and what kind of input you are expecting to receive. Materials, attestations or both. 
+
+Example:
+
+- Load the dependency track instance extension
+
+#### Registration
+
+Registration is when a specific instance of the extension is configured on a Chainloop organization. A registered instance is then available to be attached to any workflow, more on that later.
+
+Example:
+
+- Register a dependency track instance by receiving its URL and API key. At this stage, the extension will make sure that the provided information is valid and store it for later use.
+
+#### Attachment
+
+Attachment happens when a registered instance is attached to a Workflow. This means that any attestations or materials that are received by the workflow will be sent to the attached extension for processing.
+
+Example:
+
+- Tell the already registered dependency track instance to send the SBOMs to a specific project.
+
+#### Execution
+
+This is the actual execution of the extension. This is where the extension will do its work. i.e call a workflow, or send a notification.
+
+Example:
+
+In the dependency track use-case we will
+
+- Get the instance URL and API key from the state stored during the registration phase
+- Get the specific project where we want to post the SBOMs from the attachment phase
+- Send the SBOMs to the dependency track instance
+
+## How to create a new extension
+
+
+We offer a starter template in `./core/template`. Just copy it to a new folder and follow the steps shown in its readme.

app/controlplane/extensions/README.md

@@ -1,15 +1,11 @@
 version: v1
 plugins:
   - name: go
-    out: .
-    opt: paths=source_relative
-  - name: go-grpc
     out: .
     opt:
       - paths=source_relative
-  - name: go-http
-    out: .
-    opt: paths=source_relative
   - name: validate
     out: .
-    opt: paths=source_relative,lang=go
+    opt:
+      - paths=source_relative
+      - lang=go

app/controlplane/extensions/buf.gen.yaml

@@ -0,0 +1,5 @@
+### Dependency-Track fan-out Extension
+
+This extension implements sending cycloneDX Software Bill of Materials (SBOM) to Dependency-Track. 
+
+See https://docs.chainloop.dev/guides/dependency-track/