melody

Melody

Melody is a Go framework focused on building HTTP applications and CLI commands on top of the same runtime, container, configuration, logging, and validation infrastructure.

The repository also contains a complete userland showcase under ./.example/.

v3 is the stable, actively maintained version of Melody. New features land here; v1 and v2 receive fixes only. See Project status.

Getting started

Install the module:

go get github.com/precision-soft/melody/v3

A minimal HTTP application:

package main

import (
    "context"
    nethttp "net/http"

    "github.com/precision-soft/melody/v3/application"
    melodyhttp "github.com/precision-soft/melody/v3/http"
    melodyhttpcontract "github.com/precision-soft/melody/v3/http/contract"
    melodyruntimecontract "github.com/precision-soft/melody/v3/runtime/contract"
)

func main() {
    app := application.NewApplication(context.Background(), nil, nil)

    app.RegisterHttpRoute(
        "GET",
        "/health",
        func(
            runtimeInstance melodyruntimecontract.Runtime,
            writer nethttp.ResponseWriter,
            request melodyhttpcontract.Request,
        ) (melodyhttpcontract.Response, error) {
            return melodyhttp.NewResponse(nethttp.StatusOK, []byte(`{"status":"ok"}`)), nil
        },
    )

    app.Run()
}

Run it, then call the endpoint (the HTTP server listens on :8080 by default):

go run .
curl http://localhost:8080/health
# {"status":"ok"}

For a realistic, fully wired application — modules, services, security, sessions, events, CLI commands, and every platform integration — see .example/README.md.

Project status

v3 is the actively maintained version. All new features land on v3; v1 and v2 are in maintenance mode and receive security and critical correctness fixes only. Within v3, APIs that need to change are first marked with a /* Deprecated: ... */ doc comment and kept working, with a future v4 cut once enough breaking changes accumulate. See the repository README.md and CONTRIBUTING.md.

Why Melody

Melody is designed for teams that want:

• A single service container and runtime lifecycle shared by HTTP and CLI entrypoints.
• Deterministic wiring: behavior is assembled through modules, services, and explicit registration rather than global state.
• Clear boundaries between userland APIs (what you build on) and framework internals (what you do not depend on).

Architecture

At a high level, a Melody application is assembled as follows:

• Application (code) wires modules and services into a container (code).
• A runtime (code) owns the lifecycle (boot/compile/run/shutdown) and creates request/command scopes.
• HTTP (code) uses the runtime + container scopes to run middleware and dispatch handlers.
• CLI (code) runs commands inside the same runtime/container infrastructure.
• Cross-cutting packages are wired as services: logging, event, validation, cache, session, security.

The HTTP and CLI entrypoints share the same runtime and container; boot wiring happens once, then each request or command runs in its own scope:

  Application                  boot order:
  modules · services · config  modules (pre-config) -> config resolve -> modules (post-config)
        |                                            -> container -> CLI -> HTTP
        | wires
        v
  Kernel
  container · config · clock · event dispatcher · http router
        |
        | creates a scope per request / command
        v
  Runtime  -----------------------------+
        |                               |
        v                               v
  HTTP entry                      CLI entry
  middleware -> handler           command execution

Extensibility

Melody is extended primarily through:

• Modules: register services and configuration defaults.
• Services: your container registrations (including overriding framework defaults where supported).
• Events: subscribe to lifecycle and domain events.
• HTTP middleware: compose request behavior around handlers.
• CLI commands: register commands within the CLI integration.

Some APIs are intentionally closed to keep behavior deterministic and to avoid dependency on internal wiring. When an extension point exists, it is documented explicitly in the relevant package documentation.

Build tags

Melody supports two independent embedding modes controlled by build tags:

1. Environment configuration (.env-style files)
2. Static assets (filesystem vs embedded)

These are intentionally independent so you can embed one family while keeping the other on the filesystem.

1) Environment configuration (.env)

Build tag:

• melody_env_embedded

Behavior

• Without melody_env_embedded
  Environment configuration is loaded from filesystem .env files (for example .env, .env.local). This is the default for local development.

• With melody_env_embedded
  Environment configuration is embedded into the binary at build time (via Go embed). The runtime reads the embedded .env content instead of the filesystem.

Build examples

# filesystem env (default)
go build -o app ./...

# embedded env
go build -tags melody_env_embedded -o app ./...

2) Static assets

Build tag:

• melody_static_embedded

Behavior

• Without melody_static_embedded
  Static assets are served from the filesystem (for example from an application-provided public/ directory). This is the default for local development.

• With melody_static_embedded
  Static assets are embedded into the binary at build time (via Go embed). The HTTP layer serves the embedded assets.

Build examples

# filesystem static (default)
go build -o app ./...

# embedded static assets
go build -tags melody_static_embedded -o app ./...

Combining build tags

You can combine the tags to embed both families:

go build -tags "melody_env_embedded melody_static_embedded" -o app ./...

For a complete example that shows the same build-tag matrix applied end-to-end in a userland application, see .example/README.md.

Documentation

Melody documentation follows a strict, canonical structure. The documentation canon is defined in .documentation/DOCUMENTATION.md and is normative for all Markdown files in this repository.

Key entry points:

• Framework entry document: README.md
• Example application documentation: .example/README.md
• Contribution and code style rules: CONTRIBUTING.md
• Package documentation (API reference): .documentation/package/
• Roadmap (future plans): .documentation/ROADMAP.md

Packages

Each package below links to its source folder and its package documentation.

• APPLICATION — code | docs
  High-level application bootstrap, module registration, and run modes.

• BAG — code | docs
  Typed value access patterns and conversion semantics used by configuration.

• CACHE — code | docs
  In-process caching contracts and implementations.

• CLI — code | docs
  CLI contracts, command registration, and execution model.

• CLOCK — code | docs
  Clock abstraction for deterministic time and testing.

• CONFIG — code | docs
  Configuration loading and composition (file-based, env artifacts).

• CONTAINER — code | docs
  Dependency injection container, scopes, service factories, and lifecycle.

• DEBUG — code | docs
  Built-in CLI debug commands (container, events, router, middleware, parameters, versions).

• EVENT — code | docs
  Deterministic event dispatching and subscriber/listener contracts.

• EXCEPTION — code | docs
  Error wrappers, context propagation, and fail-fast helpers.

• HTTP — code | docs
  HTTP server, router integration, middleware execution, request orchestration.

• HTTPCLIENT — code | docs
  Outbound HTTP client contracts and helpers.

• KERNEL — code | docs
  Kernel integration points that connect application, runtime, and HTTP/CLI wiring.

• LOCK — code | docs
  Named distributed-lock contracts with an in-memory locker (Redis/SQL backends via integrations).

• LOGGING — code | docs
  Structured logging contracts and framework logging conventions.

• MAILER — code | docs
  Email sending over a pluggable transport (SMTP, in-memory) with RFC 5322 / MIME rendering.

• MESSAGEBUS — code | docs
  Transport-agnostic asynchronous message bus, middleware stack, routing, and consumer worker.

• OPENAPI — code | docs
  OpenAPI 3.0.3 document generation from routes and Go types.

• RUNTIME — code | docs
  Application runtime lifecycle, boot/compile/run, and wiring orchestration.

• SECURITY — code | docs
  Access control rules, authentication integration points, and security wiring.

• SERIALIZER — code | docs
  Serialization contracts and helpers for request/response boundaries.

• SESSION — code | docs
  Session storage contracts and request/session lifecycle integration.

• STORAGE — code | docs
  Object-storage contracts with a local filesystem backend (S3-compatible backend via integrations).

• TRANSLATION — code | docs
  Message catalogs with an ICU-subset formatter (placeholders, plural, select).

• VALIDATION — code | docs
  DTO validation engine, constraints, and errors.

• VERSION — code | docs
  Version metadata and helpers.

Example application

The full userland showcase lives under ./.example/. Start here:

• .example/README.md

Contributing

Development workflow and contribution rules:

• CONTRIBUTING.md