Application

The application package provides the core Application type that manages startup tasks, services, databases, and health checks throughout your application’s lifecycle.

Application Type

The Application type orchestrates the lifecycle of your application, managing startup tasks, services, databases, and health monitoring.

type Application struct {
    // Contains startup tasks, services, healthcheckers, and databases
}

Constructor

*Application

Creates and returns a new Application instance.

app := application.New()

Methods

RegisterService

void

Registers a named service with the application. Services are started concurrently when the application runs.

httpServer := httpserver.New("8080", 3*time.Second)
app.RegisterService("api", httpServer)

RegisterDatabase

void

Adds a database to the application for lifecycle management.

db, err := database.New(connStr)
if err != nil {
    log.Fatal(err)
}
app.RegisterDatabase("main", db)

RegisterRepository

void

Registers a repository with a specific database. Repositories implementing the migrator interface will have their migrations applied.

userRepo := NewUserRepository(db.Connection())
app.RegisterRepository("main", "users", userRepo)

RegisterDomain

void

Registers a domain repository in the specified database. The domain must implement the Domain interface.

authDomain := auth.NewDomain(db.Connection())
app.RegisterDomain("auth", "main", authDomain)

OnStart

void

Registers a startup task that runs before services start.

app.OnStart(migrationTask, application.StartupTaskConfig{
    Name:         "database_migration",
    AbortOnError: true,
})

OnStartFunc

void

Registers a startup task using a function.

app.OnStartFunc(func(ctx context.Context) error {
    log.InfoContext(ctx, "initializing application")
    return nil
}, application.StartupTaskConfig{
    Name:         "init",
    AbortOnError: false,
})

Health

*Health

Returns the current health status of the application and all registered services.

health := app.Health(ctx)
// Returns health status including service states

Run

error

Parses CLI arguments and executes the appropriate command.Supported commands:

run - Starts all registered services
migrate - Runs database migrations
--help, -h - Displays usage information

Returns ErrUnknownCommand if an unknown command is provided.

if err := app.Run(ctx); err != nil {
    log.ErrorContext(ctx, "app failed", "error", err)
}

Interfaces

Runner

The Runner interface defines tasks that can be executed with context.

type Runner interface {
    Run(context.Context) error
}

func(context.Context) error

Executes the task with the given context and returns an error if any.

RunnerFunc

A function type that implements the Runner interface.

type RunnerFunc func(context.Context) error

func (rf RunnerFunc) Run(ctx context.Context) error {
    return rf(ctx)
}

Domain

The Domain interface describes a domain module that exposes its repository.

type Domain interface {
    GetRepository() any
}

func() any

Returns the repository associated with this domain.

Healthchecker

Represents a service that can perform health checks.

type Healthchecker interface {
    Healthcheck(context.Context) any
}

func(context.Context) any

Returns the health status of the service. The returned value can be any serializable type.

Types

StartupTaskConfig

Configuration options for a startup task.

type StartupTaskConfig struct {
    Name         string // Name of the startup task
    AbortOnError bool   // Whether to abort application startup if this task fails
}

string

Name of the startup task for logging and identification.

bool

If true, the application will terminate if this startup task fails. If false, the error is logged and execution continues.

Errors

ErrUnknownCommand

var ErrUnknownCommand = errors.New("unknown command")

Returned when an unknown CLI command is provided to Run().

ErrDatabaseMigrationFailed

type ErrDatabaseMigrationFailed struct {
    err error
}

Returned when database migration fails during the migrate command.

ErrStartupTaskFailed

type ErrStartupTaskFailed struct {
    err error
}

Returned when a startup task with AbortOnError: true fails.

Helpers

HealthCheckHandler

An HTTP handler that serves application health information as JSON.

type HealthCheckHandler struct {
    app *Application
}

*HealthCheckHandler

Creates a health check HTTP handler for the application.Parameters:

app (*Application): The application instance to check health for

app := application.New()
healthHandler := application.NewHealthCheckHandler(app)

api := httpserver.New("8080", 3*time.Second)
api.Handle("/health", healthHandler)

The handler returns a JSON response with:

Application start time
Service statuses (NOT_STARTED, STARTED, ERROR)
Service start/stop times
Error messages for failed services
Custom health data from Healthchecker implementations

Example Usage

package main

import (
    "context"
    "time"
    "github.com/platforma-dev/platforma/application"
    "github.com/platforma-dev/platforma/httpserver"
    "github.com/platforma-dev/platforma/log"
)

func main() {
    ctx := context.Background()
    
    // Create application
    app := application.New()
    
    // Create and register HTTP server
    api := httpserver.New("8080", 3*time.Second)
    api.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        health := app.Health(r.Context())
        json.NewEncoder(w).Encode(health)
    })
    app.RegisterService("api", api)
    
    // Add startup task
    app.OnStartFunc(func(ctx context.Context) error {
        log.InfoContext(ctx, "application initialized")
        return nil
    }, application.StartupTaskConfig{
        Name:         "init",
        AbortOnError: false,
    })
    
    // Run application (handles CLI commands)
    if err := app.Run(ctx); err != nil {
        log.ErrorContext(ctx, "app error", "error", err)
    }
}

CLI Usage:

# Start the application
./myapp run

# Run database migrations
./myapp migrate

# Show help
./myapp --help

Core Packages

Domain Modules

Application Type

Constructor

Methods

RegisterService

RegisterDatabase

RegisterRepository

RegisterDomain

OnStart

OnStartFunc

Health

Run

Interfaces

Runner

RunnerFunc

Domain

Healthchecker

Types

StartupTaskConfig

Errors

ErrUnknownCommand

ErrDatabaseMigrationFailed

ErrStartupTaskFailed

Helpers

HealthCheckHandler

Example Usage

​Application Type

​Constructor

​Methods

​RegisterService

​RegisterDatabase

​RegisterRepository

​RegisterDomain

​OnStart

​OnStartFunc

​Health

​Run

​Interfaces

​Runner

​RunnerFunc

​Domain

​Healthchecker

​Types

​StartupTaskConfig

​Errors

​ErrUnknownCommand

​ErrDatabaseMigrationFailed

​ErrStartupTaskFailed

​Helpers

​HealthCheckHandler

​Example Usage

Application Type

Constructor

Methods

RegisterService

RegisterDatabase

RegisterRepository

RegisterDomain

OnStart

OnStartFunc

Health

Run

Interfaces

Runner

RunnerFunc

Domain

Healthchecker

Types

StartupTaskConfig

Errors

ErrUnknownCommand

ErrDatabaseMigrationFailed

ErrStartupTaskFailed

Helpers

HealthCheckHandler

Example Usage