Update to Metamodel Version 3.2 (#327)

* Updates Go Version and adapts SNAPSHOT Workflow (#8)

* Update to latest aas-package3-golang

* Fixes go mod

* Adapts Vuln Scan Workflow

* Updates SUPPLY_CHAIN_SECURITY.md

* Update to 3.2 dependencies

Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>

* Adapts Submodel Repository OpenAPI Yaml to Version 3.2 (incl. SSP 005, 006, 007)

* 1_1_0 Schema Update

* Updates remaining openapi.yml files

Co-authored-by: Jannik Fried <Jannik.Fried@iese.fraunhofer.de>

* Adds aaset kind migration

* Adds small fixes to openapi files

* Fixes aas env test failures

* Implements v3.2 API capabilities

* Increases test coverage and adds docu

* Fixes schema patch test

* Implement history and audit configuration with eventing support

- Added history configuration options via environment variables, including modes for history behavior (off, api, audit), retention days, immutability settings, and audit identity modes.
- Introduced ChangeEvent structure to encapsulate event data for history storage.
- Updated AppendVersionTx to append immutable event rows instead of updating existing history rows.
- Implemented SHA-256 hashing for canonical JSON snapshots and row hashes for history events.
- Added support for audit metadata in history events, including actor subject, request ID, and other contextual information.
- Created tests for history functionality, ensuring stable hashing and correct behavior under different configurations.
- Enhanced documentation to reflect new history features and configuration options.

* Implement PostgreSQL mutation guards for history tables and update related services

* Fixes failing tests

* Rem test

* 1_1_1 Changes
- changes openapi
- adds history guard

* Fixes typo

* Improves new schema changes

Co-authored-by: Jannik Fried <Jannik.Fried@iese.fraunhofer.de>

* Small fixes

* Fixes linting errors

* Resolves Review Remark

* Adapts .gitignore

* Adds missing endpoints

* Small Changes

* Improves documentation

* Adresses review remarks

* Adresses further review remarks

* Adds missing method in pkg submodel repo api

* Adresses review remarks

* Fixes swagger base path handling

* Fixes incorrect operation contracts

* Adresses Martins Remarks

* Fixes incorrect submodel repo query test setup

* Adds logging for new configs and changes order from new to old

* Prepares the new history storage diff mode

---------

Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>

Author: FriedJannik

.gitignore

@@ -47,4 +47,9 @@ debug.test.*
 .gocache/
 logs/
 
-.kilo/
+.kilo/
+
+# Generated by AAS environment serialization integration tests
+internal/aasenvironment/integration_tests/testdata_results/
+
+.cache/

README.md

@@ -200,6 +200,7 @@ See [structure.md](docu/developer/structure.md) and related files for details on
 - Example endpoint: `/submodels/{id}/submodel-elements/{idShort}/attachment`
 - AAS environment import endpoint: `/upload` (multipart/form-data with file part `file`)
 - Supported upload media types: `application/aasx+xml`, `application/aasx+json`, `application/asset-administration-shell+xml`, `application/asset-administration-shell+json`, `application/json`, `application/xml`, `text/xml`
+- AAS v3.2 history and recent changes: [user guide](docu/user/aas_api_v3_2.md) and [runtime notes](docu/developer/aas_v3_2_runtime.md)
 - See [structure_cmd.md](docu/developer/structure_cmd.md) for details
 
 ## 9. Contribution Guidelines

cmd/aasenvironmentservice/main.go

@@ -29,6 +29,7 @@ package main
 import (
 	"context"
 	"crypto/rsa"
+	"database/sql"
 	"embed"
 	"flag"
 	"fmt"
@@ -44,6 +45,7 @@ import (
 	aasrepositorydb "github.com/eclipse-basyx/basyx-go-components/internal/aasrepository/persistence"
 	"github.com/eclipse-basyx/basyx-go-components/internal/common"
 	"github.com/eclipse-basyx/basyx-go-components/internal/common/asyncbulk"
+	"github.com/eclipse-basyx/basyx-go-components/internal/common/history"
 	"github.com/eclipse-basyx/basyx-go-components/internal/common/jws"
 	commonmodel "github.com/eclipse-basyx/basyx-go-components/internal/common/model"
 	auth "github.com/eclipse-basyx/basyx-go-components/internal/common/security"
@@ -79,6 +81,13 @@ func runServer(ctx context.Context, configPath string) error {
 	if err := commonmodel.SetVerificationMode(cfg.Server.StrictVerification); err != nil {
 		return err
 	}
+	history.Configure(history.Config{
+		Mode:                 cfg.History.Mode,
+		RetentionDays:        cfg.History.RetentionDays,
+		FullSnapshotInterval: cfg.History.FullSnapshotInterval,
+		Immutability:         cfg.History.Immutability,
+		AuditIdentityMode:    cfg.History.AuditIdentityMode,
+	})
 
 	registrySyncConfig, err := aasenvironment.NewRegistrySyncConfig(
 		cfg.General.AASRegistryIntegration,
@@ -118,16 +127,10 @@ func runServer(ctx context.Context, configPath string) error {
 		return err
 	}
 
-	sharedDB, err := common.NewDatabaseConnection(dsn)
+	sharedDB, err := openSharedDatabase(ctx, cfg, dsn)
 	if err != nil {
 		return err
 	}
-	if cfg.Postgres.MaxOpenConnections > 0 {
-		sharedDB.SetMaxOpenConns(cfg.Postgres.MaxOpenConnections)
-	}
-	if cfg.Postgres.MaxIdleConnections > 0 {
-		sharedDB.SetMaxIdleConns(cfg.Postgres.MaxIdleConnections)
-	}
 
 	var privateKey *rsa.PrivateKey
 	if cfg.JWS.PrivateKeyPath != "" {
@@ -149,6 +152,7 @@ func runServer(ctx context.Context, configPath string) error {
 	if err != nil {
 		return err
 	}
+	aasRepositoryPersistence.SetJWSPrivateKey(privateKey)
 	submodelRepositoryPersistence, err := submodelrepositorydb.NewSubmodelDatabaseFromDB(sharedDB, privateKey, cfg.Server.StrictVerification)
 	if err != nil {
 		return err
@@ -220,35 +224,51 @@ func runServer(ctx context.Context, configPath string) error {
 	if err = auth.SetupSecurity(ctx, cfg, apiRouter); err != nil {
 		return err
 	}
+	versioningGuard := history.NewMutationCoverageGuard(apiRouter)
+	apiRouter.Use(versioningGuard.Middleware)
 
-	for _, rt := range aasRegistryCtrl.Routes() {
+	for operation, rt := range aasRegistryCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
-	for _, rt := range smRegistryCtrl.Routes() {
+	for operation, rt := range smRegistryCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
-	for _, rt := range aasRepositoryCtrl.Routes() {
+	for operation, rt := range aasRepositoryCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
-	for _, rt := range smRepositoryCtrl.Routes() {
+	for operation, rt := range smRepositoryCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
-	for _, rt := range cdrCtrl.Routes() {
+	for operation, rt := range cdrCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
-	for _, rt := range discoveryCtrl.Routes() {
+	for operation, rt := range discoveryCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
-	for _, rt := range descriptionCtrl.Routes() {
+	for operation, rt := range descriptionCtrl.Routes() {
+		versioningGuard.ClassifyRoute(operation, rt.Method, rt.Pattern)
 		apiRouter.Method(rt.Method, rt.Pattern, rt.HandlerFunc)
 	}
+	versioningGuard.Cover(http.MethodPost, "/bulk/shell-descriptors")
+	versioningGuard.Cover(http.MethodPut, "/bulk/shell-descriptors")
+	versioningGuard.Cover(http.MethodDelete, "/bulk/shell-descriptors")
+	versioningGuard.Exempt(http.MethodPost, "/bulk/submodel-descriptors")
+	versioningGuard.Exempt(http.MethodPut, "/bulk/submodel-descriptors")
+	versioningGuard.Exempt(http.MethodDelete, "/bulk/submodel-descriptors")
 	aasBulkHandler.RegisterRoutes(apiRouter, true)
 	smBulkHandler.RegisterRoutes(apiRouter, false)
 
 	r.Mount(base, apiRouter)
 
 	// Register /upload endpoint
 	uploadService := aasenvironment.NewUploadAPIService(persistence, customAASRepository, customSMRepository)
+	versioningGuard.Cover(http.MethodPost, "/upload")
 	aasenvironment.RegisterUploadAPI(apiRouter, uploadService, cfg.General.UploadMaxSizeBytes)
 	aasenvironment.RegisterSerializationAPI(apiRouter, serializationService)
 
@@ -291,6 +311,30 @@ func runServer(ctx context.Context, configPath string) error {
 	return nil
 }
 
+func openSharedDatabase(ctx context.Context, cfg *common.Config, dsn string) (*sql.DB, error) {
+	db, err := common.NewDatabaseConnection(dsn)
+	if err != nil {
+		return nil, err
+	}
+	configurePostgresPool(db, cfg.Postgres)
+	if err = history.ApplyPostgresGuardConfig(ctx, db); err != nil {
+		return nil, err
+	}
+	return db, nil
+}
+
+func configurePostgresPool(db *sql.DB, cfg common.PostgresConfig) {
+	if cfg.MaxOpenConnections > 0 {
+		db.SetMaxOpenConns(cfg.MaxOpenConnections)
+	}
+	if cfg.MaxIdleConnections > 0 {
+		db.SetMaxIdleConns(cfg.MaxIdleConnections)
+	}
+	if cfg.ConnMaxLifetimeMinutes > 0 {
+		db.SetConnMaxLifetime(time.Duration(cfg.ConnMaxLifetimeMinutes) * time.Minute)
+	}
+}
+
 func main() {
 	ctx := context.TODO()
 	configPath := ""