feat!: Upgrade to OpenAPI v3

Upgrading from Swagger to OpenAPI v3 offers numerous benefits, including
enhanced specification features, better support for modern use cases,
improved developer experience, access to a richer ecosystem and tooling,
future-proofing our API specifications, and ensuring
compliance and interoperability.

This change replaces the existing code generator, resulting in changes
to the generated model. Users of the Go client library will need to make
minor adjustments to their code.

Signed-off-by: Michael Adler <michael.adler@siemens.com>

.ci/packages/versions.env

@@ -11,3 +11,4 @@ export SWAGGER_VERSION=0.31.0 # github-releases/go-swagger/go-swagger&versioning
 export ZIG_VERSION=0.13.0 # github-releases/ziglang/zig&versioning=semver
 export MARKDOWN_LINK_CHECK_VERSION=3.12.2 # github-releases/tcort/markdown-link-check&versioning=semver
 export SYFT_VERSION=1.17.0 # github-releases/anchore/syft&versioning=semver
+export OAPI_CODEGEN_VERSION=2.3.0 # github-releases/oapi-codegen/oapi-codegen&versioning=semver

.gitignore

@@ -15,7 +15,6 @@ cmd/wfx-viewer/wfx-viewer
 coverage*
 *.log
 /results
-generated/wfx.swagger.yml
 /out
 *.cov
 /wfx.db*

.golangci.yml

@@ -19,18 +19,6 @@ run:
     - postgres
     - mysql
 
-  # default is true. Enables skipping of directories:
-  #   vendor$, third_party$, testdata$, examples$, Godeps$, builtin$
-  skip-dirs-use-default: true
-
-  # which files to skip: they will be analyzed, but issues from them
-  # won't be reported. Default value is empty list, but there is
-  # no need to include all autogenerated files, we confidently recognize
-  # autogenerated files. If it's not please let us know.
-  # "/" will be replaced by current OS file path separator to properly work
-  # on Windows.
-  skip-files: []
-
   # by default isn't set. If set we pass it to "go list -mod={option}". From "go help modules":
   # If invoked with -mod=readonly, the go command is disallowed from the implicit
   # automatic updating of go.mod described above. Instead, it fails when any changes
@@ -47,10 +35,6 @@ run:
 
 # output configuration options
 output:
-  # colored-line-number|line-number|json|tab|checkstyle|code-climate|junit-xml|github-actions
-  # default is "colored-line-number"
-  format: colored-line-number
-
   # print lines of code with issue, default is true
   print-issued-lines: true
 
@@ -92,7 +76,6 @@ linters:
 
 linters-settings:
   staticcheck:
-    go: "1.21"
     # https://staticcheck.io/docs/options#checks
     checks: ["all", "-ST1000", "-SA1019"]
   misspell:
@@ -107,3 +90,8 @@ linters-settings:
   dupword:
     keywords:
       - "INSTALLING"
+  stylecheck:
+    checks: [
+        "all",
+        "-ST1003", # allow method names such as GetJobsIdTags
+      ]

.goreleaser.yml

@@ -21,6 +21,7 @@ builds:
       - postgres
       - mysql
       - plugin
+      - swagger
     flags:
       - -trimpath
       - -mod=readonly
@@ -54,9 +55,9 @@ builds:
       - -mod=readonly
     ldflags:
       - -s -w -linkmode external -extldflags '-static'
-      - -X github.com/siemens/wfxctl/cmd/wfx/metadata.Version={{.Version}}
-      - -X github.com/siemens/wfxctl/cmd/wfx/metadata.Commit={{.Commit}}
-      - -X github.com/siemens/wfxctl/cmd/wfx/metadata.Date={{.CommitDate}}
+      - -X github.com/siemens/wfx/cmd/wfxctl/metadata.Version={{.Version}}
+      - -X github.com/siemens/wfx/cmd/wfxctl/metadata.Commit={{.Commit}}
+      - -X github.com/siemens/wfx/cmd/wfxctl/metadata.Date={{.CommitDate}}
     env:
       - CGO_ENABLED=1
     goos:

CHANGELOG.md

@@ -9,20 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `wfxctl workflow query` now accepts a `sort` param
+- Added (existing but undocumented) `/health` and `/version` endpoint to OpenAPI spec
+- OpenAPI v3 spec is served at `/api/wfx/v1/openapiv3.json`
+
 ### Fixed
 
-- `wfx` would not start if it was built without plugins support
+- `wfx`: implemented sort functionality for `/workflows` endpoint
 
 ### Changed
 
-- Use zstd instead of xz to compress release tarballs
-
-## [0.3.1] - 2024-07-09
+- Migrated from Swagger to OpenAPI v3
+- The previous Swagger spec is still served at `/api/wfx/v1/swagger.json` (but no longer at the top level `/swagger.json`).
+  in order to *maintain compatibility* with older clients (e.g., SWUpdate <= 2024.12). The endpoint will be removed
+  in a future release.
+- `wfxctl workflow get` uses southbound API by default
+- `wfxctl health` validates the certificate chain when using TLS
+- Forbbiden requests (e.g. job creation via southbound API) now return HTTP status code 403 instead of 405
+- System certificates will be loaded automatically for TLS communication
 
-### Added
+## [0.3.2] - 2024-09-03
 
 ### Fixed
 
+- `wfx` would not start if it was built without plugins support
+
+## [0.3.1] - 2024-07-09
+
 ### Changed
 
 - Use zstd instead of xz to compress release tarballs
@@ -44,8 +57,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Log messages from automaxprocs/maxprocs are now seamlessly integrated into existing logging framework
 
-### Removed
-
 ## [0.2.0] - 2024-01-15
 
 ### Added
@@ -67,8 +78,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Empty or `null` arrays are omitted from JSON responses
 - Build requires Go >= 1.21
 
-### Removed
-
 ## [0.1.0] - 2023-02-06
 
 Initial release of wfx.
@@ -77,4 +86,5 @@ Initial release of wfx.
 [0.2.0]: https://github.com/siemens/wfx/releases/tag/v0.2.0
 [0.3.0]: https://github.com/siemens/wfx/releases/tag/v0.3.0
 [0.3.1]: https://github.com/siemens/wfx/releases/tag/v0.3.1
-[unreleased]: https://github.com/siemens/wfx/compare/v0.3.1...HEAD
+[0.3.2]: https://github.com/siemens/wfx/releases/tag/v0.3.2
+[unreleased]: https://github.com/siemens/wfx/compare/v0.3.2...HEAD

Makefile

@@ -13,7 +13,7 @@ MAKEFLAGS += --jobs=$(shell nproc)
 DESTDIR ?=
 prefix ?= /usr/local
 
-GO_TAGS = sqlite,postgres,mysql,plugin
+GO_TAGS = sqlite,postgres,mysql,plugin,swagger
 
 export CGO_ENABLED=1
 

README.md

@@ -58,7 +58,7 @@ An exemplary [Kanban](https://en.wikipedia.org/wiki/Kanban)-inspired [workflow](
   - Extendable modularized source code architecture
   - Lightweight, no dependencies (statically linked binaries)
   - Efficient, native code for a wide variety of platforms and operating systems (as supported by the [Go](https://golang.org/) Language)
-  - Fully documented REST API, see [wfx OpenAPI Specification](spec/wfx.swagger.yml)
+  - Fully documented REST API, see [wfx OpenAPI Specification](spec/wfx.openapiv3.yml)
   - Extensive test suite including load tests
 - Deployment / Usability
   - Load / Unload workflows at run-time

api/errors.go

@@ -8,35 +8,35 @@ package api
  * Author: Michael Adler <michael.adler@siemens.com>
  */
 
-import "github.com/siemens/wfx/generated/model"
+import "github.com/siemens/wfx/generated/api"
 
 /* these are defined in the swagger yaml */
 
-var InvalidRequest = model.Error{
+var InvalidRequest = api.Error{
 	Code:    "wfx.invalidRequest",
 	Message: "The request was invalid and/or could not be completed by the storage",
 	Logref:  "96a37ea1f7d205ffbfa12334c6812727",
 }
 
-var JobNotFound = model.Error{
+var JobNotFound = api.Error{
 	Code:    "wfx.jobNotFound",
 	Logref:  "11cc67762090e15b79a1387eca65ba65",
 	Message: "Job ID was not found",
 }
 
-var WorkflowNotFound = model.Error{
+var WorkflowNotFound = api.Error{
 	Code:    "wfx.workflowNotFound",
 	Logref:  "c452719774086b6e803bb8f6ecea9899",
 	Message: "Workflow not found for given name",
 }
 
-var WorkflowNotUnique = model.Error{
+var WorkflowNotUnique = api.Error{
 	Code:    "wfx.workflowNotUnique",
 	Logref:  "e1ee1f2aea859b9dd34579610e386da6",
 	Message: "Workflow with name already exists",
 }
 
-var WorkflowInvalid = model.Error{
+var WorkflowInvalid = api.Error{
 	Code:    "wfx.workflowInvalid",
 	Logref:  "18f57adc70dd79c7fb4f1246be8a6e04",
 	Message: "Workflow validation failed",

api/job_events_test.go

@@ -23,7 +23,7 @@ import (
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/job"
 	"github.com/siemens/wfx/internal/handler/job/events"
 	"github.com/siemens/wfx/internal/handler/job/status"
@@ -74,7 +74,7 @@ func TestJobEventsSubscribe(t *testing.T) {
 				events.ShutdownSubscribers()
 			}()
 
-			_, err := job.CreateJob(context.Background(), db, &model.JobRequest{ClientID: clientID, Workflow: wf.Name})
+			_, err := job.CreateJob(context.Background(), db, &api.JobRequest{ClientID: clientID, Workflow: wf.Name})
 			require.NoError(t, err)
 
 			wg.Add(1)
@@ -85,7 +85,7 @@ func TestJobEventsSubscribe(t *testing.T) {
 					time.Sleep(20 * time.Millisecond)
 				}
 				// update job
-				_, err = status.Update(context.Background(), db, *jobID.Load(), &model.JobStatus{State: "INSTALLING"}, model.EligibleEnumCLIENT)
+				_, err = status.Update(context.Background(), db, *jobID.Load(), &api.JobStatus{State: "INSTALLING"}, api.CLIENT)
 				require.NoError(t, err)
 			}()
 

api/job_id_test.go

@@ -14,7 +14,6 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/middleware/jq"
 	"github.com/siemens/wfx/persistence"
 	"github.com/steinfletcher/apitest"
 	jsonpath "github.com/steinfletcher/apitest-jsonpath"
@@ -47,9 +46,6 @@ func TestJobGetIdFilter(t *testing.T) {
 	job := persistJob(t, db)
 	jobPath := fmt.Sprintf("/api/wfx/v1/jobs/%s", job.ID)
 
-	north = jq.MW{}.Wrap(north)
-	south = jq.MW{}.Wrap(south)
-
 	// read job
 	handlers := []http.Handler{north, south}
 	for i, name := range allAPIs {
@@ -94,7 +90,7 @@ func TestDeleteJob(t *testing.T) {
 		Delete(jobPath).
 		ContentType("application/json").
 		Expect(t).
-		Status(http.StatusMethodNotAllowed).
+		Status(http.StatusForbidden).
 		End()
 
 	// delete job shall succeed for north

api/job_status_test.go

@@ -14,7 +14,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/job"
 	"github.com/siemens/wfx/internal/handler/workflow"
 	"github.com/siemens/wfx/workflow/dau"
@@ -66,7 +66,7 @@ func TestJobStatusUpdate(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.PhasedWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 	}

api/job_tag_test.go

@@ -14,7 +14,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/job"
 	"github.com/siemens/wfx/internal/handler/workflow"
 	"github.com/siemens/wfx/workflow/dau"
@@ -29,7 +29,7 @@ func TestJobTagGet(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 		Tags:     []string{"foo", "bar"},
@@ -59,7 +59,7 @@ func TestJobTagPost(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 		Tags:     []string{"tag1"},
@@ -85,8 +85,10 @@ func TestJobTagPost(t *testing.T) {
 		apitest.New().
 			Handler(south).
 			Post(jobPath).
+			ContentType("application/json").
+			Body(`["bar", "foo"]`).
 			Expect(t).
-			Status(http.StatusMethodNotAllowed).
+			Status(http.StatusForbidden).
 			End()
 	})
 }
@@ -98,7 +100,7 @@ func TestJobTagDelete(t *testing.T) {
 	wf, err := workflow.CreateWorkflow(context.Background(), db, dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	jobReq := model.JobRequest{
+	jobReq := api.JobRequest{
 		ClientID: "foo",
 		Workflow: wf.Name,
 		Tags:     []string{"foo", "bar"},
@@ -124,8 +126,10 @@ func TestJobTagDelete(t *testing.T) {
 		apitest.New().
 			Handler(south).
 			Delete(jobPath).
+			ContentType("application/json").
+			Body(`["foo"]`).
 			Expect(t).
-			Status(http.StatusMethodNotAllowed).
+			Status(http.StatusForbidden).
 			End()
 	})
 }

api/jobs_test.go

@@ -14,7 +14,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/siemens/wfx/generated/model"
+	"github.com/siemens/wfx/generated/api"
 	"github.com/siemens/wfx/internal/handler/workflow"
 	"github.com/siemens/wfx/persistence"
 	"github.com/siemens/wfx/workflow/dau"
@@ -30,14 +30,12 @@ func TestGetJobsHandler_Group(t *testing.T) {
 	workflow, err := db.CreateWorkflow(context.Background(), dau.DirectWorkflow())
 	require.NoError(t, err)
 
-	_, err = db.CreateJob(context.Background(), &model.Job{
+	_, err = db.CreateJob(context.Background(), &api.Job{
 		ClientID: "foo",
-		Status: &model.JobStatus{
-			State:    "INSTALL",
-			Progress: 0,
-			Message:  "",
+		Status: &api.JobStatus{
+			State: "INSTALL",
 		},
-		Workflow: &model.Workflow{Name: workflow.Name},
+		Workflow: &api.Workflow{Name: workflow.Name},
 	})
 	assert.NoError(t, err)
 
@@ -111,6 +109,6 @@ func TestCreateJob_SouthNotAllowed(t *testing.T) {
 		Body(`{"clientId":"gotest","workflow":"wfx.workflow.kanban","tags":[]}`).
 		ContentType("application/json").
 		Expect(t).
-		Status(http.StatusMethodNotAllowed).
+		Status(http.StatusForbidden).
 		End()
 }