Contributing

This page summarizes the layout, scripts, and conventions of the fountain repository. The remote of record is GitLab.

Repository layout

• fountain.go, fountain_init.go, options.go, auxiliary.go — framework entry point and lifecycle (the singleton Fountain struct, New(), Serving()).
• runnable/ — AppInstance, Invoker, JobInstance interfaces and lifecycle primitives.
• core/ — the CoreController interface, controller registration, and the observer pattern for cross-controller events.
• clients/ — protocol clients: fhttp_client/, fgrpc_client/, ftcp_client/, fudp_client/, fquic_client/.
• libs/ — utility libraries (prefixed f* by convention):
  • fnet/ — server implementations: fhttp (Fiber), fgrpc, ftcp, fudp, fquic.
  • flog/ — structured logging.
  • stored/ — storage backends: fedis (Redis), fongo, fcql, felastic, fbolt, and others.
  • cache/ — redis_cache/, memcache/, lfu_cache/, lru_cache/, arc_cache/.
  • brokers/ — message brokers (NATS, Kafka, RabbitMQ, MQTT) and pubsub pipelines.
  • auth_token/, social_auth/, firebase_auth/ — authentication.
  • sd/ — service discovery (fconsul, fetcd, fregistry, k8s).
  • ftracer/, metrics/, fsentinel/, resilient/ — observability and resilience.
  • base/ — utility packages (arr_util, string_util, time_util, dump, fgo worker pool, and more).
  • ferr/, fflag/, env/, fcontext/, fsync/, validator/, noti/.
• internal/ — cmd/, encoding/ (framework-private).
• constants/ — global constants (K-prefixed, UPPER_SNAKE_CASE).
• dal/ — data access layer abstractions.
• proto/ — Protocol Buffer definitions.
• examples/ — runnable examples per component; the best place to find usage patterns.
• docs/ — technical docs and migration guides.
• scripts/ — build and tooling scripts (see below).

Common commands / scripts

The scripts/ directory contains the build and tooling helpers:

• build.sh — production build with CGO_ENABLED=0 and -ldflags "-s -w" (compresses output with upx when available).
• tidy.sh — runs dos2unix on scripts/* and go mod tidy.
• download_deps.sh — go mod download plus installing dev tools (e.g. dlv).
• gosec.sh — runs the gosec security scan (gosec -fmt=json -out=gosec.json excluding testdata and test).
• swag.sh — generates OpenAPI docs via swag init and post-processes the output to OpenAPI 3.0.0.
• protoc_install.sh — installs the protoc plugins (protoc-gen-go, protoc-gen-go-grpc, protoc-gen-grpc-gateway, protoc-gen-validate).
• pre-commit.sh — installs and updates the pre-commit hooks.
• line_ending.sh — normalizes line endings (git config core.autocrlf false and re-checkout).

Do not commit local replace directives

build.sh and tidy.sh strip replace directives from go.mod before running (both the inline replace ... => ... form and the replace ( ... ) block). Do not commit local replace directives to go.mod.

Pre-commit hooks (gitleaks, gitlint, large-file/secret checks) run on commit; don't bypass them.

Conventions

See Core Concepts for the architectural background behind these conventions.

• Package naming: library packages are prefixed f<name>/ (e.g. flog, fedis, fhttp, fgrpc); client directories are f<protocol>_client/.
• Constants: K-prefixed and UPPER_SNAKE_CASE.
• Controllers: named controller.go within their domain package.
• Import ordering: stdlib → third-party → gitlab.soludian.com/soludian/fountain/... → local.
• Logging: use flog (logger := flog.NewFountainLoggerOnce()); do not use the stdlib log package.
• Errors: use the wrapping and handling helpers in libs/ferr/.

Storage migration

libs/stored/fedis_old/ is being replaced by libs/stored/fedis/. New code should use fedis. See TODO.md in the fountain repository for the migration checklist.