Skip to content

README.md

Latest commit

 

History

History
141 lines (108 loc) · 4.48 KB

README.md

File metadata and controls

141 lines (108 loc) · 4.48 KB
Raw

kernel

Tier: Foundational · Status: Full · Java original: firefly-common · .NET project: FireflyFramework.Kernel

Overview

kernel is the shared-vocabulary tier of the framework. It exposes the four primitives every Firefly module agrees on:

  1. The RFC 7807 ProblemDetail envelope.
  2. The generic Result[T] success-or-failure wrapper.
  3. The Clock abstraction for testable time.
  4. The FireflyError typed exception family.

Every method in every other module returns one of these types. The wire-shape is identical to the Java firefly-common module and the .NET FireflyFramework.Kernel project — a service running version X on any of the three runtimes emits the same JSON.

Why a separate module?

Java's Throwable hierarchy and .NET's Exception family are stable language fixtures. Go's error interface is intentionally minimal — which means every framework that wants typed error codes / structured fields / HTTP status mapping has to invent its own. kernel provides the canonical type so the whole platform agrees, and so the wire is identical across runtimes.

Public surface

ProblemDetail (RFC 7807)

The canonical application/problem+json envelope.

Member Behaviour
Type URI reference identifying the problem class
Title Short, human-readable summary
Status HTTP status code
Detail Specific to this occurrence
Instance URI of the request that produced the problem
Extensions RFC 7807 §3.2 extension members; flattened on MarshalJSON

Constructors emit the canonical type URIs (https://fireflyframework.org/problems/<kind>): ProblemBadRequest, ProblemUnauthorized, ProblemForbidden, ProblemNotFound, ProblemConflict, ProblemUnprocessable, ProblemRateLimited, ProblemInternal, ProblemValidation.

Result[T]

Generic success-or-failure envelope. Use the (value T, err error) return idiom in normal Go code; reach for Result[T] only at module boundaries that pass a single value through pipelines.

r := kernel.Ok(42)
v, err := r.Value()           // 42, nil
mapped := kernel.MapResult(r, strconv.Itoa) // Result[string]

Clock

type Clock interface { Now() time.Time }

Implementations: SystemClock, FixedClock{T: ...}, MutableClock (thread-safe; Advance(d) for tests).

FireflyError + errors

type FireflyError struct {
    Code   string
    Title  string
    Status int
    Detail string
    Fields map[string]any
    Cause  error
}

Constructors NewBadRequest(...), NewUnauthorized(...), NewForbidden(...), NewNotFound(...), NewConflict(...), NewValidation(...), NewRateLimited(...), NewInternal(...), NewIdempotencyConflict(...) return values that errors.Is / errors.As correctly. Helpers: IsFirefly(err), StatusOf(err), AsProblem(err) (renders any error as a ProblemDetail).

Correlation context

ctx = kernel.WithCorrelationID(ctx, "abc-123")
id, ok := kernel.CorrelationIDFrom(ctx)
fresh := kernel.NewCorrelationID() // 32-char hex

HeaderCorrelationID (X-Correlation-Id) and HeaderIdempotencyKey (Idempotency-Key) are exported for cross-module agreement.

Version

kernel.Version is the released framework version ("26.05.01" at the time of writing) — embedded in the actuator /version payload and the startup banner.

Quick start

import (
    "errors"
    "github.com/fireflyframework/fireflyframework-go/kernel"
)

func charge(orderID string) error {
    if orderID == "" {
        return kernel.NewBadRequest("order id required").WithField("field", "orderId")
    }
    // … domain logic …
    return nil
}

// In a handler:
if err := charge(""); err != nil {
    var fe *kernel.FireflyError
    if errors.As(err, &fe) {
        // Use fe.Status (400) and fe.ToProblem() to render RFC 7807.
    }
}

Testing

cd kernel
go test ./...

Suite covers JSON round-trip on ProblemDetail (with extension flattening), Result[T] map / flat-map, every FireflyError constructor, the clock variants, and correlation-id context propagation.