Skip to content

v4.0.0

Choose a tag to compare

View all tags
@flc1125 flc1125 released this 27 Jul 00:48
· 190 commits to 4.x since this release
v4.0.0
This tag was signed with the committer’s verified signature.
flc1125 Flc゛
GPG key ID: A041C0C291BCBD65
Verified
Learn about vigilant mode.
3060ce1
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Fries v4.0.0

v4.0.0 is the first stable release of Fries v4.

Fries v4 moves the repository to /v4 module paths, upgrades Kratos integrations to Kratos v3, adopts the standard library log/slog model, and stabilizes the context-aware component APIs introduced throughout the v4 prerelease cycle.

Compared with v4.0.0-beta.3, this release adds standalone Health and JSON Response components, extracts pointer helpers into ptr/v4, consolidates root examples into component documentation, and refreshes dependencies across the multi-module repository.

Important

Applications upgrading from v4.0.0-beta.3 must migrate support.Ptr and support.Val to ptr/v4. Applications upgrading from Fries v3 or an earlier v4 prerelease should also review the major v4 migration checklist below.

Upgrade

Fries is a multi-module repository. Upgrade the root module and every component module used by the application to the same stable version.

go get github.com/go-fries/fries/v4@v4.0.0
go get github.com/go-fries/fries/health/v4@v4.0.0
go get github.com/go-fries/fries/http/response/v4@v4.0.0
go get github.com/go-fries/fries/ptr/v4@v4.0.0
go mod tidy
go test ./...

Replace the example component modules with those imported by the application. Modules that depend on other Fries modules should use the same Fries release.

Highlights

  • Establish the stable Fries v4 module set with /v4 import paths, Kratos v3 integrations, and standard-library log/slog support.
  • Use context-aware Lifecycle, Retry, Poll, Parallel, Locker, and Event components with explicit cancellation, ownership, concurrency, and error behavior.
  • Add named application health checks with bounded concurrency, structured reports, panic recovery, and standard liveness and readiness HTTP handlers.
  • Add framework-neutral JSON response envelopes with explicit HTTP status handling, safe serialization, and application-defined error mapping.
  • Move pointer construction and optional pointer access into the focused ptr/v4 module.
  • Keep usage guidance close to component APIs through README documentation and package-local compile-checked examples.

Changes since v4.0.0-beta.3

Health checks

#2654 adds github.com/go-fries/fries/health/v4 for named, context-aware application health checks.

A registry runs a stable snapshot of checks with a shared timeout and bounded concurrency. Results remain in registration order, ordinary failures do not stop other checks, and checker panics are returned as structured PanicError results instead of terminating the process.

Use separate registries for liveness and readiness:

readiness := health.New(
	health.WithTimeout(2*time.Second),
	health.WithConcurrency(4),
)
readiness.Register("database", health.CheckFunc(db.PingContext))

liveness := health.New()

mux.Handle("/readyz", health.Handler(readiness))
mux.Handle("/livez", health.Handler(liveness))

The HTTP handler supports GET and HEAD, returns 200 OK for healthy reports and 503 Service Unavailable for unhealthy reports, and hides raw checker errors by default.

Note

Enable health.WithErrorDetails() only for protected internal endpoints when exposing raw dependency errors is acceptable.

JSON responses

#2658 adds github.com/go-fries/fries/http/response/v4 for consistent JSON response envelopes without coupling callers to a web framework.

body := response.Success(
	"Scratch 11 is working properly.",
	scratch,
	response.WithCode(10000),
)

if err := response.Write(w, http.StatusOK, body); err != nil {
	return err
}

The real HTTP status remains explicit and independent from the application-defined code. Success, Failure, and FromError construct response bodies, while ErrorMapper and ErrorMapperFunc centralize conversion from domain errors to HTTP status, business code, and public message.

response.Write serializes the complete body before committing HTTP headers, so JSON encoding failures remain observable.

Warning

Use FromError only when the error text is safe to expose. Map internal and unknown errors to a public fallback message.

Pointer helpers

#2656 removes support.Ptr and support.Val and introduces the focused github.com/go-fries/fries/ptr/v4 module.

Pointer API mapping

Before After
support.Ptr(value) ptr.Ptr(value)
support.Val(pointer) ptr.Value(pointer) or ptr.Or(pointer, fallback)

Before:

value := support.Ptr("fries")
result := support.Val(value)

After:

value := ptr.Ptr("fries")

result, present := ptr.Value(value)
fallbackResult := ptr.Or(value, "default")

Migration requirements:

  1. Add github.com/go-fries/fries/ptr/v4 to the consuming module.
  2. Replace support.Ptr(value) with ptr.Ptr(value).
  3. Replace support.Val(pointer) with ptr.Value(pointer) when the nil state must be observed.
  4. Use ptr.Or(pointer, fallback) when a fallback value is required.
  5. Remove the support/v4 dependency when no other Support API is used.

ptr.Value(nil) returns the type's zero value and false. A non-nil pointer to a zero value returns that value and true. ptr.Or uses its fallback only when the pointer itself is nil.

Component documentation and examples

#2688 removes the repository-level examples/ directory and keeps usage guidance beside the components it documents.

Removed example module Replacement
github.com/go-fries/fries/examples/cache/v4 cache/README.md
github.com/go-fries/fries/examples/cloudevents/amqp091/v4 cloudevents/protocol/amqp091/README.md
github.com/go-fries/fries/examples/cloudevents/eventdispatcher/v4 cloudevents/eventdispatcher/README.md and example_test.go
github.com/go-fries/fries/examples/mysql/canal/v4 mysql/canal/README.md

These modules were excluded from releases and exposed only executable package main programs. No releasable library component was removed. Nested component examples such as queue/examples/tasker and eino/components/embedding/cached/example remain available.

Major v4 migration checklist

Applications upgrading directly from Fries v3 should review the following changes:

  1. Replace Fries imports from /v3 with /v4.
  2. Upgrade github.com/go-kratos/kratos/v2 imports and dependencies to Kratos v3.
  3. Replace contract/v4 with capability/v4.
  4. Replace legacy kratos/log/* components with log/slog/* or the official OpenTelemetry otelslog bridge, and pass *slog.Logger to component logger options.
  5. Replace the old Filesystem API with the streaming filesystem.Driver contract and optional capability interfaces.
  6. Replace coroutines/v4 with the context-aware parallel/v4 APIs.
  7. Replace the Hashing global registry with reusable hash constructors and typed digests.
  8. Construct built-in codecs as zero-value concrete types such as json.Codec{}.
  9. Replace support.Retry with retry/v4, and replace legacy polling and timeout helpers with poll/v4 and standard Go Context deadlines.
  10. Replace foundation/v4 with lifecycle/v4.
  11. Migrate Locker to the reusable Locker -> Lock -> Lease ownership model.
  12. Replace eventbus/v4 with the synchronous, type-aware event/v4 Dispatcher.
  13. Replace support.Ptr and support.Val with ptr/v4.

Detailed API mappings, before-and-after examples, and behavioral notes are available in the prerelease documentation:

  • v4.0.0-beta.1: /v4 module paths, Kratos v3, log/slog, Capability, and OpenTelemetry alignment.
  • v4.0.0-beta.2: Filesystem, Parallel, Hashing, Codec, Retry, Poll, Hyperf Jet Retry, Support, and Queue.
  • v4.0.0-beta.3: Lifecycle, Locker, Event, and removal of legacy Support polling and timeout helpers.

What's changed

Breaking API changes

  • #2656 refactor(support)!: extract pointer helpers

Features

  • #2654 feat(health): add health check component
  • #2658 feat(http): add JSON response component

Documentation and repository structure

  • #2688 refactor: consolidate examples with component documentation

Dependencies

  • #2651 fix(deps): update module github.com/aws/aws-sdk-go-v2/service/s3 to v1.105.2
  • #2650 fix(deps): update module github.com/aliyun/alibabacloud-oss-go-sdk-v2 to v1.5.3
  • #2649 chore(deps): update module github.com/dlclark/regexp2/v2 to v2.5.1
  • #2653 fix(deps): update golang.org/x to 764159d
  • #2655 chore(deps): update module github.com/dlclark/regexp2/v2 to v2.5.2
  • #2660 chore(deps): update module github.com/klauspost/compress to v1.19.1
  • #2659 chore(deps): update github.com/charmbracelet/ultraviolet digest to 7cc6674
  • #2670 chore(deps): update module github.com/prometheus/common to v0.70.1
  • #2669 fix(deps): update module github.com/cloudwego/eino to v0.9.13
  • #2667 fix(deps): update module github.com/rabbitmq/amqp091-go to v1.13.0
  • #2666 chore(deps): update module github.com/prometheus/client_golang to v1.24.0
  • #2665 chore(deps): update module github.com/nunnatsa/ginkgolinter to v0.23.1
  • #2664 chore(deps): update module github.com/go-logr/logr to v1.4.4
  • #2668 fix(deps): update aws-sdk-go-v2 monorepo
  • #2662 chore(deps): update googleapis to 0afa2a6
  • #2663 chore(deps): update module github.com/ebitengine/purego to v0.10.2
  • #2674 chore(deps): update module github.com/leodido/go-urn to v1.5.0
  • #2672 chore(deps): update module buf.build/gen/go/bufbuild/bufplugin/protocolbuffers/go to v1.36.11-20260722160903-4d94f3df3a7b.1
  • #2671 chore(deps): update module github.com/gabriel-vasile/mimetype to v1.4.14
  • #2679 chore(deps): update module github.com/mattn/go-isatty to v0.0.24
  • #2678 chore(deps): update module github.com/gabriel-vasile/mimetype to v1.4.15
  • #2675 chore(deps): update github.com/timakin/bodyclose digest to 857993a
  • #2677 chore(deps): update googleapis to 3fe39f3
  • #2682 chore(deps): update module github.com/go-git/go-billy/v5 to v5.9.1
  • #2681 chore(deps): update github.com/petermattis/goid digest to f64c70f
  • #2680 chore(deps): update module github.com/mattn/go-runewidth to v0.0.27
  • #2683 chore(deps): update module github.com/prometheus/client_golang to v1.24.1
  • #2673 chore(deps): update module go.opentelemetry.io/proto/otlp to v1.11.0
  • #2687 chore(deps): update module github.com/docker/go-connections to v0.8.0
  • #2686 chore(deps): update github.com/petermattis/goid digest to 500c67a
  • #2685 chore(deps): update module github.com/quic-go/quic-go to v0.61.0
  • #2684 chore(deps): update googleapis to b2f2020
  • #2690 chore(deps): update module go.yaml.in/yaml/v3 to v3.0.5
  • #2689 chore(deps): update module github.com/google/cel-go to v0.30.0

Release

Full Changelog: v4.0.0-beta.3...v4.0.0

Assets 2
Loading