Disable known responders optimization in TESTING

v1.17.1 disables the known responders optimization in unit tests by default because it introduces a level of non-determinism that can fail tests randomly. Specifically, publishers may or may not detect replies from new subscribers in the first attempt of a multicast.

Refer to v1.17.0 for important release notes.

Reimagined integration test harness

Summary

v1.17.0 reimagines the integration testing harness, simplifying its coding patterns significantly. Other improvements include changes to the code-generated client, new pub options, and more.

What's New?

• Revamped the code-generated testing harness. The old testing harness in integration-gen_test.go has been deprecated. Tests are now 100% self-contained in service_test.go
• Modified the client signatures of web endpoints. The functions taking an http.Request as argument were removed.
• Modified the clients to be passed by value rather than with a pointer
• New pub options: pub.Actor and pub.RelativeURL
• Adjusted order of precedence of path, body and query args. This change should have no impact unless you submit the same named argument via more than one of these 3 mechanisms
• Improved the code generator to not require insertion point markers in the code. The <--IMPORT and <--NEW markers added in the v1.16.0 were eliminated

Breaking Changes

Go Generate

Force run the code generator at the root of the project.

CODEGEN=-f go generate ./...

Clients

Correct any build errors working with clients, in particular when calling web endpoints.

If you've used the versions that take in http.Request, use the equivalent pub.Option in client.WithOptions(...). For example, to pass headers:

anyserviceapi.NewClient(svc).WithOptions(pub.Header("Key", "Value")).RenderPage(ctx, "")

If you've used the _Get or _Post versions, modify accordingly. For example:

anyserviceapi.NewClient(svc).RenderPage(ctx, "POST", "", "application/json", body)

If you've created extension methods to clients, change their received to take in the struct, not a pointer to it. For example:

func (_c Client) MyExtentionMethod(ctx context.Context, ...) {
    ...
}

Integration Tests

The existing integration tests in integration_test.go and integration-gen_test.go are unaltered and should continue to work. However, they will no longer be maintained as new changes are made to service.yaml. It is highly recommended to port the tests to the new pattern in service.go. Refer to the documentation for guidance.

• Add _Old to the names of the tests in integration_test.go.
• Run go generate in the directory of the service to generate the new testing harness in service_test.go.
• Migrate over the tests from integration_test.go to service_test.go.

Codegen improvements

Summary

v1.16.0 brings a couple of improvements to the code generator and updates dependencies to the latest version.

What's New?

The code generator now automates the bootstrapping of new Microbus projects. See documentation for details.

Markers were added to main/main.go to help the code generator insert new microservices into the main app automatically. Existing code bases are advised to add the <--IMPORT and <--NEW markers manually.

import (
    ...
    // <--IMPORT
)

func main() {
    ...
    add.Add(
        // Solution microservices
        // <--NEW
    ) 
    ...
}

Bug fix: redact error detail in PROD

This minor release fixes a bug in v1.15.0 that caused the details of an error to be redacted in all environments other than PROD, rather than only in PROD.

Error marshaling

Summary

v1.15.0 alters the way errors are marshaled in order to make parsing of responses easier for web clients.

Error responses are now marshaled under an "err" property whereas earlier they were marshaled at the root of the document. Scoping the error under the "err" property guarantees no chance of a naming conflict between the return arguments and the properties of the error. With this change, client applications can parse the response into a single object and look for a non-empty "err" to indicate an error, just like the idiomatic Go pattern. They no longer have to look at the HTTP status code in order to determine what the response will include.

{
	"err": {
		"error": "message",
		"stack": [...],
		"statusCode": 500,
		"trace": "0123456789abcdef0123456789abcdef",
		"propName": "propValue"
	}
}

What's New?

• Fixed bug that prevented Microbus from running purely with the short-circuit transport
• Resolved data race in tracing span
• Introduced a variadic API for setting attributes on a tracing span
• Improved the token issuer to not override any claims provided in the request to allow using it as a derivative issuer
• Errors returned by endpoints are marshaled as {"err":{...}} to facilitate parsing by web clients
• Added support for using %w when creating a new error
• Made trace ID a first-degree property of the error
• Improved browser detection in the error page redirection middleware by examining the User-Agent header

Breaking Changes

Since the marshaling of errors between microservices has changed, all microservices must be rebuilt and redeployed.

If you need to maintain backward compatibility with external web clients, set the LegacyErrorPrinter in your middleware with:

httpIngressSvc.Middleware().Replace(httpingress.ErrorPrinter, middleware.LegacyErrorPrinter(func() string {
	return svc.Deployment()
}))

Short-circuit transport

Summary

v1.14.0 includes important improvements to performance and reliability and is recommended for all users.

What's New?

• Introduced the short-circuit transport that enables microservices that are bundled together in the same executable to communicate in-memory without having to go to the messaging bus
• Reduced memory allocations
• Fixed data races
• Fixed bug in defragging of large payloads
• Assured zero impact when distributed tracer is disabled
• Fixed bug in definition of Grafana dashboards
• MICROBUS_PROMETHEUS_EXPORTER environment variable is now required for microservices to collect metrics that can be pulled by Prometheus. Pushing metrics to OpenTelemetry is unaffected
• Differentiated frame.ContextWithFrameOf and frame.ContextWithClonedFrameOf

Breaking Changes

• Run CODEGEN=-f go generate ./... at the root of the project to regenerate the integration test harness
• Set the environment variable MICROBUS_PROMETHEUS_EXPORTER to 1 or true if you're pulling metrics to Prometheus via the metrics core microservice. This is not required if you're pushing metrics via OpenTelemetry

Fix semantic version

Summary

A quick release to fix the semantic version to have 3 parts.

What's New

• Update semantic version to v1.13.1

Enhanced error management

Summary

This release enhances the TracedError struct used to wrap errors. Most notably, it introduces a property bag that can associate arbitrary key-value pairs with the error.

What's New

• Errors are now written to the HTTP response as JSON, not text, making it easier for clients to parse them in a structured way
• Arbitrary key-value pairs can be associated with errors and used later by a middleware to customize responses
• New smart variadic versions of errors.New and errors.Trace
• The error printer middleware was improved to render errors as JSON, and redact error details depending on the situation
• A new charset UTF-8 middleware was added to the pipeline to specify charset for textual content types

Various improvements

What's New?

• Client WithOptions
• Improvements of the Grafana dashboards
• Replaced JSON omitempty with omitzero across the board
• Deprecated and removed the timex package
• Colorful log handler for LOCAL development
• Changed semantics of frame.ContextWithFrameOf and frame.ContextWithFrame
• Restrict SetConfig and ResetConfig to TESTING deployments only
• Allow hyphens and underscores in config and ticker names
• Handle non-standard paths and package names in code generation

Breaking Changes

If you experience a compilation error in the integration test harness, force code generation using CODEGEN=-f go generate . in the directory of the microservice.

For extra prudence, run CODEGEN=-f go generate ./... in the root of the project to regenerate all microservices.

The timex package was removed. If you rely on this package, refer to https://github.com/microbus-io/timex for instructions how to migrate.

OpenTelemetry metrics

This release introduces the option to push metrics via OpenTelemetry, which is now the default. The option to pull metrics via a Prometheus scrape is still supported.

The quick setup is updated to use the all-in-one Grafana LGTM image instead of separately Jaeger, Prometheus and Grafana.

Metrics can now be observed "just in time" using a callback.

BREAKING CHANGE: The names and definitions of several of the metrics produced by Microbus were changed. Updated versions of the bundled dashboards can be imported to Grafana from ./setup/grafana/dashboards. Existing custom dashboards require manual adjustment.

BREAKING CHANGE: The logger attribute "host" was renamed to "service".