refactor: move all packages under pkg/ for v5 by gfyrag · Pull Request #559 · formancehq/go-libs

gfyrag · 2026-03-05T22:49:35Z

Summary

Full repository restructure for v5: all Go packages are now under pkg/ for a cleaner and more consistent organization.

What changes

13 directories moved into pkg/: authn/, cloud/, errors/, fx/, messaging/, observe/, query/, service/, storage/, testing/, transport/, types/, workflow/
All import paths change from github.com/formancehq/go-libs/v5/<pkg> to github.com/formancehq/go-libs/v5/pkg/<pkg>
The module path (github.com/formancehq/go-libs/v5) remains unchanged

Cleanup included

.golangci.yml: fix stale v4 path to CircuitBreaker → v5
pkg/authn/oidc/verifier.go: replace deprecated str.Contains with stdlib slices.Contains, update TODO(v4) → TODO
coverage.txt: delete stale file (v3 data)
pkg/testing/platform/pgtesting/postgres.go: fix Docker timeout not being propagated — MaximumWaitingTime and StatusCheckInterval were never passed to docker.Configuration, causing timeouts in CI when multiple PostgreSQL tests run in parallel

Resulting structure

go-libs/
├── docs/
└── pkg/
    ├── types/          # Layer 0 — leaf packages (pointer, time, currency, collections, metadata)
    ├── errors/         # Layer 0
    ├── query/          # Layer 0
    ├── observe/        # Layer 1 — log, traces, metrics, profiling
    ├── storage/        # Layer 1 — postgres, bun, migrations, s3
    ├── authn/          # Layer 1 — jwt, oidc, licence
    ├── transport/      # Layer 2 — httpserver, grpcserver, api, httpclient
    ├── messaging/      # Layer 2 — publish, queue, circuit breaker
    ├── workflow/       # Layer 2 — temporal
    ├── cloud/          # Layer 2 — aws/iam
    ├── service/        # Layer 3 — app bootstrap, health
    ├── fx/             # Layer 4 — FX wiring modules
    └── testing/        # Layer 5 — test infra, docker, platform containers

See docs/ARCHITECTURE.md for full documentation on dependency rules and conventions.

Test plan

go build ./... passes
go vet ./... passes
golangci-lint run ./... passes (0 issues)
go test ./... passes (all 21+ packages, including PostgreSQL integration tests)
No stale import paths remaining (verified with grep)

🤖 Generated with Claude Code

coderabbitai · 2026-03-05T22:49:54Z

Important

Review skipped

Too many files!

This PR contains 269 files, which is 119 over the limit of 150.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 69391a96-20a1-4b85-8e88-e031cae52d85

📥 Commits

Reviewing files that changed from the base of the PR and between 464ee02 and 4ef50ac.

⛔ Files ignored due to path filters (3)

.golangci.yml is excluded by !**/*.yml
go.mod is excluded by !**/*.mod
go.sum is excluded by !**/*.sum, !**/*.sum

📒 Files selected for processing (269)

auth/cli.go
auth/module.go
ballast/ballast.go
ballast/module.go
bun/bunpaginate/main_test.go
docs/ARCHITECTURE.md
docs/CONTRIBUTING.md
health/module.go
licence/cli.go
licence/cli_test.go
otlp/cli.go
otlp/module.go
otlp/otlpmetrics/otlpexporter.go
otlp/otlpmetrics/stdoutexporter.go
otlp/otlptraces/cli_test.go
otlp/otlptraces/otlpexporter.go
otlp/otlptraces/stdoutexporter.go
otlp/otlptraces/traces_test.go
pkg/authn/jwt/additional_checks.go
pkg/authn/jwt/additional_checks_test.go
pkg/authn/jwt/auth.go
pkg/authn/jwt/auth_test.go
pkg/authn/jwt/authenticator.go
pkg/authn/jwt/authenticator_generated.go
pkg/authn/jwt/control_plane_agent.go
pkg/authn/jwt/control_plane_agent_generated.go
pkg/authn/jwt/control_plane_agent_test.go
pkg/authn/jwt/flags.go
pkg/authn/jwt/middleware.go
pkg/authn/jwt/middleware_test.go
pkg/authn/jwt/module.go
pkg/authn/jwt/module_test.go
pkg/authn/jwt/no_auth.go
pkg/authn/jwt/scopes.go
pkg/authn/licence/cli_prod.go
pkg/authn/licence/flags.go
pkg/authn/licence/flags_test.go
pkg/authn/licence/jwt.go
pkg/authn/licence/licence.go
pkg/authn/licence/licence_test.go
pkg/authn/licence/public_key.go
pkg/authn/oidc/README.md
pkg/authn/oidc/authorization.go
pkg/authn/oidc/client/device.go
pkg/authn/oidc/client/discover.go
pkg/authn/oidc/client/errors.go
pkg/authn/oidc/client/introspect.go
pkg/authn/oidc/client/jwks.go
pkg/authn/oidc/client/relying_party.go
pkg/authn/oidc/client/signing.go
pkg/authn/oidc/client/token.go
pkg/authn/oidc/client/token_client_credentials.go
pkg/authn/oidc/client/token_code_exchange.go
pkg/authn/oidc/client/token_exchange.go
pkg/authn/oidc/client/token_refresh.go
pkg/authn/oidc/client/user_info.go
pkg/authn/oidc/client/verifier.go
pkg/authn/oidc/code_challenge.go
pkg/authn/oidc/device_authorization.go
pkg/authn/oidc/discovery.go
pkg/authn/oidc/error.go
pkg/authn/oidc/http/cookie.go
pkg/authn/oidc/http/http.go
pkg/authn/oidc/http/marshal.go
pkg/authn/oidc/introspection.go
pkg/authn/oidc/keyset.go
pkg/authn/oidc/organization_aware_access_token_claims.go
pkg/authn/oidc/revocation.go
pkg/authn/oidc/session.go
pkg/authn/oidc/token.go
pkg/authn/oidc/token_exchange.go
pkg/authn/oidc/token_request.go
pkg/authn/oidc/types.go
pkg/authn/oidc/userinfo.go
pkg/authn/oidc/util.go
pkg/authn/oidc/verifier.go
pkg/cloud/aws/iam/load.go
pkg/errors/errors.go
pkg/errors/errors_test.go
pkg/fx/authnfx/jwt.go
pkg/fx/authnfx/licence.go
pkg/fx/messagingfx/publish.go
pkg/fx/messagingfx/publish_test.go
pkg/fx/observefx/metrics.go
pkg/fx/observefx/profiling.go
pkg/fx/observefx/resource.go
pkg/fx/observefx/traces.go
pkg/fx/servicefx/health.go
pkg/fx/storagefx/bunconnect.go
pkg/fx/storagefx/s3.go
pkg/fx/transportfx/grpcserver.go
pkg/fx/transportfx/httpserver.go
pkg/fx/workflowfx/temporal.go
pkg/messaging/publish/circuit/circuit_breaker.go
pkg/messaging/publish/circuit/circuit_breaker_test.go
pkg/messaging/publish/circuit/storage/migrations.go
pkg/messaging/publish/circuit/storage/storage.go
pkg/messaging/publish/circuit/utils_test.go
pkg/messaging/publish/flags.go
pkg/messaging/publish/http.go
pkg/messaging/publish/iam.go
pkg/messaging/publish/kafka.go
pkg/messaging/publish/kafka_scram.go
pkg/messaging/publish/logging.go
pkg/messaging/publish/logging_test.go
pkg/messaging/publish/messages.go
pkg/messaging/publish/module.go
pkg/messaging/publish/nats.go
pkg/messaging/publish/sns.go
pkg/messaging/publish/sqs.go
pkg/messaging/publish/topicmap/topic_mapper.go
pkg/messaging/queue/listener.go
pkg/messaging/queue/listener_generated.go
pkg/messaging/queue/listener_test.go
pkg/messaging/queue/localstack_integration_test.go
pkg/observe/error.go
pkg/observe/flags.go
pkg/observe/http_client.go
pkg/observe/log/adapter_hclog.go
pkg/observe/log/adapter_hclog_test.go
pkg/observe/log/adapter_logrus.go
pkg/observe/log/adapter_zap.go
pkg/observe/log/context.go
pkg/observe/log/flags.go
pkg/observe/log/logging.go
pkg/observe/log/logging_generated.go
pkg/observe/log/logrus_trace_hook.go
pkg/observe/log/stream.go
pkg/observe/metrics/exporter_inmemory.go
pkg/observe/metrics/exporter_noop.go
pkg/observe/metrics/flags.go
pkg/observe/metrics/module.go
pkg/observe/metrics/otlpexporter.go
pkg/observe/metrics/stdoutexporter.go
pkg/observe/module.go
pkg/observe/otlp.go
pkg/observe/profiling/flags.go
pkg/observe/profiling/module.go
pkg/observe/recover.go
pkg/observe/traces/flags.go
pkg/observe/traces/flags_test.go
pkg/observe/traces/otlpexporter.go
pkg/observe/traces/stdoutexporter.go
pkg/observe/traces/traces.go
pkg/observe/traces/traces_test.go
pkg/query/expression.go
pkg/query/expression_test.go
pkg/query/mapping.go
pkg/service/app.go
pkg/service/context.go
pkg/service/execute.go
pkg/service/flags.go
pkg/service/flags_test.go
pkg/service/health/controller.go
pkg/service/health/controller_test.go
pkg/service/health/health.go
pkg/storage/bun/connect/connect.go
pkg/storage/bun/connect/connect_test.go
pkg/storage/bun/connect/flags.go
pkg/storage/bun/connect/iam.go
pkg/storage/bun/connect/tracer.go
pkg/storage/bun/debug/debug_hook.go
pkg/storage/bun/explain/explain_hook.go
pkg/storage/bun/migrate/command.go
pkg/storage/bun/migrate/run.go
pkg/storage/bun/migrate/run_test.go
pkg/storage/bun/paginate/bigint.go
pkg/storage/bun/paginate/cursor.go
pkg/storage/bun/paginate/iterate.go
pkg/storage/bun/paginate/main_test.go
pkg/storage/bun/paginate/pagination.go
pkg/storage/bun/paginate/pagination_column.go
pkg/storage/bun/paginate/pagination_column_test.go
pkg/storage/bun/paginate/pagination_offset.go
pkg/storage/bun/paginate/pagination_offset_test.go
pkg/storage/bun/paginate/pagination_query_options.go
pkg/storage/migrations/flags.go
pkg/storage/migrations/migration.go
pkg/storage/migrations/migrator.go
pkg/storage/migrations/migrator_test.go
pkg/storage/migrations/versions.go
pkg/storage/postgres/errors.go
pkg/storage/postgres/errors_test.go
pkg/storage/s3/module.go
pkg/storage/s3/s3.go
pkg/testing/api/matchers.go
pkg/testing/api/utils.go
pkg/testing/deferred/deferred.go
pkg/testing/deferred/ginkgo/helpers.go
pkg/testing/docker/ginkgo/ginkgo.go
pkg/testing/docker/pool.go
pkg/testing/migrations/testing.go
pkg/testing/platform/clickhousetesting/clickhouse.go
pkg/testing/platform/clickhousetesting/ginkgo.go
pkg/testing/platform/elastictesting/elastic.go
pkg/testing/platform/localstacktesting/localstack.go
pkg/testing/platform/localstacktesting/localstack_test.go
pkg/testing/platform/natstesting/ginkgo.go
pkg/testing/platform/natstesting/nats.go
pkg/testing/platform/pgtesting/README.md
pkg/testing/platform/pgtesting/ginkgo.go
pkg/testing/platform/pgtesting/postgres.go
pkg/testing/platform/pgtesting/postgres_test.go
pkg/testing/platform/temporaltesting/temporal.go
pkg/testing/testservice/ginkgo/helpers.go
pkg/testing/testservice/instrumentation.go
pkg/testing/testservice/instrumentation_debug.go
pkg/testing/testservice/instrumentation_grpcserver.go
pkg/testing/testservice/instrumentation_httpserver.go
pkg/testing/testservice/instrumentation_nats.go
pkg/testing/testservice/instrumentation_otlp.go
pkg/testing/testservice/instrumentation_output.go
pkg/testing/testservice/instrumentation_postgres.go
pkg/testing/testservice/logger.go
pkg/testing/testservice/service.go
pkg/testing/utils/testing_main.go
pkg/transport/api/handler_info.go
pkg/transport/api/handler_info_test.go
pkg/transport/api/idempotency.go
pkg/transport/api/idempotency_test.go
pkg/transport/api/link.go
pkg/transport/api/link_test.go
pkg/transport/api/logging_chi.go
pkg/transport/api/logging_chi_test.go
pkg/transport/api/query.go
pkg/transport/api/query_test.go
pkg/transport/api/response.go
pkg/transport/api/response_test.go
pkg/transport/api/response_utils.go
pkg/transport/api/utils.go
pkg/transport/api/utils_test.go
pkg/transport/grpcserver/serverport.go
pkg/transport/httpclient/debug.go
pkg/transport/httpserver/middlewares.go
pkg/transport/httpserver/otelmiddleware.go
pkg/transport/httpserver/otlp_middleware.go
pkg/transport/httpserver/serverport.go
pkg/transport/serverport/serverport.go
pkg/types/collections/linked_list.go
pkg/types/collections/linked_list_test.go
pkg/types/collections/map.go
pkg/types/collections/map_test.go
pkg/types/collections/slice.go
pkg/types/collections/slice_test.go
pkg/types/currency/amount.go
pkg/types/currency/amount_test.go
pkg/types/currency/currency.go
pkg/types/currency/currency_test.go
pkg/types/metadata/metadata.go
pkg/types/metadata/owner.go
pkg/types/pointer/utils.go
pkg/types/pointer/utils_test.go
pkg/types/time/time.go
pkg/types/time/time_test.go
pkg/workflow/temporal/client.go
pkg/workflow/temporal/encryption.go
pkg/workflow/temporal/encryption_test.go
pkg/workflow/temporal/flags.go
pkg/workflow/temporal/logger.go
pkg/workflow/temporal/worker.go
profiling/module.go
publish/circuit_breaker/module.go
publish/circuit_breaker/storage/module.go
publish/cli.go
publish/module.go
publish/sns.go
publish/sqs.go
s3bucket/module.go
temporal/client_module.go

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch refacto/structure

📝 Coding Plan

Generate coding plan for human review comments

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gfyrag · 2026-03-05T22:54:09Z

A proposal guys! Waiting for you feeback!

fguery · 2026-03-09T09:02:45Z

+never imports cobra or interacts with CLI frameworks directly beyond pflag.
+
+`*cobra.Command` is only accepted in `service/`, `fx/`, and CLI builder packages
+(e.g. `storage/bun/migrate/`). Pure packages accept `*pflag.FlagSet` and


Yes -- but I'm not sure what we loose :/

Would you prefer to depends only on standard flags package?
(From my memory, we can bind flags)

Yes -- but I'm not sure what we loose :/

Both are not interchangeable.
So, either we add an abstraction layer, either we just define cobra will be our by default cli builder (which is fine imho)

I don't even know the alternatvies to Cobra, so I don't think I'm the best person to decide on that -- but to me it might be good enough to depend on it.

Let's just stick to cobra if we don't have a specific reason to switch away?

Yes, we don't have reasons to change I think.
And if it was the case, I guess this is easily automatable.

codecov · 2026-03-19T15:56:28Z

Codecov Report

❌ Patch coverage is 13.80400% with 818 lines in your changes missing coverage. Please review.
✅ Project coverage is 25.83%. Comparing base (464ee02) to head (4ef50ac).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/fx/messagingfx/publish.go	22.49%	284 Missing and 2 partials ⚠️
pkg/workflow/temporal/client.go	0.00%	57 Missing ⚠️
pkg/fx/workflowfx/temporal.go	0.00%	52 Missing ⚠️
pkg/fx/authnfx/jwt.go	0.00%	43 Missing ⚠️
pkg/fx/observefx/traces.go	0.00%	43 Missing ⚠️
pkg/fx/authnfx/licence.go	0.00%	38 Missing ⚠️
pkg/messaging/publish/flags.go	0.00%	37 Missing ⚠️
pkg/fx/observefx/metrics.go	0.00%	36 Missing ⚠️
pkg/messaging/publish/module.go	0.00%	26 Missing ⚠️
pkg/authn/jwt/flags.go	0.00%	19 Missing ⚠️
... and 32 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #559      +/-   ##
==========================================
- Coverage   28.80%   25.83%   -2.98%     
==========================================
  Files         175      180       +5     
  Lines        7071     7065       -6     
==========================================
- Hits         2037     1825     -212     
- Misses       4914     5130     +216     
+ Partials      120      110      -10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Move all 13 top-level Go packages into pkg/ for a cleaner repository structure. All internal import paths updated from github.com/formancehq/go-libs/v5/<pkg> to github.com/formancehq/go-libs/v5/pkg/<pkg>. Also includes cleanup: - Fix .golangci.yml stale v4 CircuitBreaker path - Replace deprecated str.Contains with stdlib slices.Contains - Update TODO(v4) markers to TODO - Delete stale coverage.txt - Fix pgtesting timeout not being propagated to docker pool - Update docs/ARCHITECTURE.md to reflect new structure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove unused type aliases (Authenticator, KeySet) from authnfx - Remove unused `debug` parameter from S3ModuleFromFlags - Delete comment-only stub files in messaging/publish/circuit/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Standardize naming across all packages: cli.go -> flags.go since these files all serve the same purpose (flag definitions). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Generated mock files had stale package names from before the pkg/ move, causing import cycles and build failures with --build-tags it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fguery · 2026-03-19T16:48:57Z

-	otelMetricsKeepInMemory, _ := cmd.Flags().GetBool(OtelMetricsKeepInMemoryFlag)
-
-	return MetricsModule(ModuleConfig{
+func ConfigFromFlags(flags *flag.FlagSet) ModuleConfig {


in my mind the conversation about cobra meant we'd revert to pass around cmd *cobra.Command instead of flag.FlatSet.
Not a blocker though.

gfyrag requested a review from a team as a code owner March 5, 2026 22:49

laouji reviewed Mar 6, 2026

View reviewed changes

Comment thread pkg/cloud/aws/iam/load.go

Comment thread pkg/fx/storagefx/s3.go

fguery reviewed Mar 9, 2026

View reviewed changes

paul-nicolas reviewed Mar 9, 2026

View reviewed changes

Comment thread pkg/authn/jwt/module.go Outdated

paul-nicolas reviewed Mar 9, 2026

View reviewed changes

Comment thread pkg/messaging/publish/circuit/storage/module.go Outdated

paul-nicolas reviewed Mar 9, 2026

View reviewed changes

Comment thread pkg/messaging/publish/circuit/module.go Outdated

paul-nicolas reviewed Mar 9, 2026

View reviewed changes

Comment thread pkg/authn/jwt/flags.go

gfyrag force-pushed the refacto/structure branch from a55fcab to 14b39b5 Compare March 19, 2026 15:21

gfyrag requested review from a team as code owners March 19, 2026 15:21

gfyrag and others added 6 commits March 19, 2026 17:01

chore: rename cli.go to flags.go for consistency

09cf1d4

Standardize naming across all packages: cli.go -> flags.go since these files all serve the same purpose (flag definitions). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: rename

779a0bd

chore(deps): update all dependencies

0a863cc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: resolve package name mismatches in generated mocks

4ef50ac

Generated mock files had stale package names from before the pkg/ move, causing import cycles and build failures with --build-tags it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gfyrag force-pushed the refacto/structure branch from 82ff0b5 to 4ef50ac Compare March 19, 2026 16:02

gfyrag requested review from fguery, laouji and paul-nicolas March 19, 2026 16:08

fguery approved these changes Mar 19, 2026

View reviewed changes

paul-nicolas approved these changes Mar 20, 2026

View reviewed changes

gfyrag added this pull request to the merge queue Mar 20, 2026

Merged via the queue into main with commit 65990f7 Mar 20, 2026
7 checks passed

gfyrag deleted the refacto/structure branch March 20, 2026 09:17

Conversation

gfyrag commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changes

Cleanup included

Resulting structure

Test plan

Uh oh!

coderabbitai Bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

gfyrag commented Mar 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fguery Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gfyrag Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

fguery Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gfyrag Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

fguery Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

laouji Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

gfyrag Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

fguery Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gfyrag commented Mar 5, 2026 •

edited

Loading

coderabbitai Bot commented Mar 5, 2026 •

edited

Loading

fguery Mar 9, 2026 •

edited

Loading

fguery Mar 9, 2026 •

edited

Loading

codecov Bot commented Mar 19, 2026 •

edited

Loading