v0 Breaking Changes

A description of breaking changes introduced in v0 of sysl-go and their remediation measures.

• v0.1.0 - Build metadata
• v0.5.0 - Error mapping
• v0.13.0 - Load config
• v0.17.0 - Config validator
• v0.28.0 - GRPC interceptor

v0.1.0 - Build metadata

https://github.com/anz-bank/sysl-go/releases/tag/v0.1.0 - 4e7e986

Introduces build metadata within sysl-go.

Remediation

1. Remove metadata parameter from core.Server

// old
core.Server(ctx, name, handler, grpc, logger, registry, buildMetadata)

// new
core.Server(ctx, name, handler, grpc, logger, registry)

2. Move build flags to core namespace

# old
go build -ldflags="-X main.Name=foo"

# new
go build -ldflags "-X github.com/anz-bank/sysl-go/core.Name=foo"

v0.5.0 - Error mapping

https://github.com/anz-bank/sysl-go/releases/tag/v0.5.0 - d749e18

This change does the following:

1. Introduce error types defined in sysl
2. Change the interaction between the framework and custom code to support internal error handling.

Remediation

1. Upgrade sysl to v0.42.0 or above.

2. Change RestGenCallback HandleError to MapError

// old
// HandleError allows custom HTTP errors to be added to `sys-go` errors
HandleError(ctx context.Context, w http.ResponseWriter, kind common.Kind, message string, cause error)

// new
// MapError maps an error to an HTTPError in instances where custom error mapping is 
// required. Return nil to perform default error mapping; defined as: 
// 1. CustomError.HTTPError if the original error is a CustomError, otherwise
// 2. common.MapError
MapError(ctx context.Context, err error) *common.HTTPError

Please note that the err passed through is currently guaranteed to be a ServerError however this is subject to change.

3. Replace custom error handling with sysl errors (optional)

!type BusinessLogicError [~error]:
    http_status <: string [value = "500"]
    http_code <: string [value = "1001"]
    http_message <: string [value = "Business logic error"]

Errors defined in sysl can be used an as error and will automatically be mapped to an appropriate HTTPError if nil is returned from MapError.

v0.13.0 - Load config

This change does the following:

1. Renames config.ReadConfig to config.LoadConfig.
2. Validates the loaded config with validator.Validate.

Remediation

1. Change calls from config.ReadConfig to config.LoadConfig.

v0.17.0 - Config validator

https://github.com/anz-bank/sysl-go/releases/tag/v0.17.0 - eedeba9

The current declaration of Config instances within sysl-go have a requirement that they are validator.Validator instances. This removes the necessity for config to be a validator.

This change does the following:

1. Change Config return type in handlerinitialiser.HandlerInitialiser interface.
2. Change Config return type in core.RestGenCallback interface

Remediation

1. Update Config in handlerinitialiser.HandlerInitialiser.

// old:
type HandlerInitialiser interface
    Config() validator.Validator
}

// new:
type HandlerInitialiser interface {
    Config() interface{}
}

2. Update Config in core.RestGenCallback.

// old:
type RestGenCallback interface {
    Config() validator.Validator
}

// new:
type RestGenCallback interface {
    Config() interface{}
}

v0.28.0 - GRPC interceptor

https://github.com/anz-bank/sysl-go/releases/tag/v0.28.0 - 453f8db

This change does the following:

1. Adds the Interceptors method to the core.GrpcManager interface.

Remediation

1. Add the Interceptors method to the core.GrpcManager implementation.

func (h *CustomGrpcManager) Interceptors() []grpc.UnaryServerInterceptor {
    return []grpc.UnaryServerInterceptor{}
}

[WIP] Admin config

Separates admin server and config from REST and GRPC managers.

This change does the following:

1. Renames Manager to RestManager.
2. Renames HandlerInitialiser to RestHandlerInitialiser.
3. Moves LibraryConfig from RestManager (previously Manager) to core.Server argument.
4. Moves the AdminServerConfig from RestManager (previously Manager) to LibraryConfig.

Remediation

1. Fix compilation issues due to HandlerInitialiser rename:

// old
func (h *HandlerManager) EnabledHandlers() []handlerinitialiser.HandlerInitialiser { ... }

// new
func (h *HandlerManager) EnabledHandlers() []handlerinitialiser.RestHandlerInitialiser { ... }

2. Pass LibraryConfig into core.Server:

// old
func Server(
    ctx context.Context, 
    name string, 
    rest RestManager, 
    grpc GrpcManager, 
    logger *logrus.Logger, 
    prom *prometheus.Registry)

// new
func Server(
    ctx context.Context, 
    name string, 
    cfg *config.LibraryConfig  // new
    rest RestManager, 
    grpc GrpcManager, 
    logger *logrus.Logger, 
    prom *prometheus.Registry)

3. Move adminServer config to config.yaml root:

# old
server:  # or other custom name
  adminServer:
    contextTimeout: 2s
    http:
        basePath: /admin
    ...

# new
adminServer:
  contextTimeout: 2s
  http:
      basePath: /admin
  ...