gui/docs/framework/core.md

Core API Reference

Complete API reference for the Core framework (pkg/core).

Core Struct

The central application container.

Creation

func New(opts ...Option) (*Core, error)

Creates a new Core instance with the specified options.

Methods

Service Access

func ServiceFor[T any](c *Core, name string) (T, error)

Retrieves a service by name with type safety.

func MustServiceFor[T any](c *Core, name string) T

Retrieves a service by name, panics if not found or wrong type.

Actions

func (c *Core) ACTION(msg Message) error

Broadcasts a message to all registered action handlers.

func (c *Core) RegisterAction(handler func(*Core, Message) error)

Registers an action handler.

Service Registration

func (c *Core) AddService(name string, svc any) error

Manually adds a service to the registry.

Config Access

func (c *Core) Config() *config.Service

Returns the config service if registered.

Options

WithService

func WithService(factory ServiceFactory) Option

Registers a service using its factory function.

c, _ := core.New(
    core.WithService(config.Register),
    core.WithService(display.NewService),
)

WithName

func WithName(name string, factory ServiceFactory) Option

Registers a service with an explicit name.

c, _ := core.New(
    core.WithName("mydb", database.NewService),
)

WithAssets

func WithAssets(assets embed.FS) Option

Sets embedded assets for the application.

WithServiceLock

func WithServiceLock() Option

Prevents late service registration after initialization.

ServiceFactory

type ServiceFactory func(c *Core) (any, error)

Factory function signature for service creation.

Message

type Message interface{}

Messages can be any type. Common patterns:

// Map-based message
c.ACTION(map[string]any{
    "action": "user.created",
    "id":     "123",
})

// Typed message
type UserCreated struct {
    ID    string
    Email string
}
c.ACTION(UserCreated{ID: "123", Email: "user@example.com"})

ServiceRuntime

Generic helper for services that need Core access.

type ServiceRuntime[T any] struct {
    core    *Core
    options T
}

Creation

func NewServiceRuntime[T any](c *Core, opts T) *ServiceRuntime[T]

Methods

func (r *ServiceRuntime[T]) Core() *Core
func (r *ServiceRuntime[T]) Options() T
func (r *ServiceRuntime[T]) Config() *config.Service

Usage

type MyOptions struct {
    Timeout time.Duration
}

type MyService struct {
    *core.ServiceRuntime[MyOptions]
}

func NewMyService(c *core.Core) (any, error) {
    opts := MyOptions{Timeout: 30 * time.Second}
    return &MyService{
        ServiceRuntime: core.NewServiceRuntime(c, opts),
    }, nil
}

func (s *MyService) DoSomething() {
    timeout := s.Options().Timeout
    cfg := s.Config()
    // ...
}

Lifecycle Interfaces

Startable

type Startable interface {
    OnStartup(ctx context.Context) error
}

Implement for initialization on app start.

Stoppable

type Stoppable interface {
    OnShutdown(ctx context.Context) error
}

Implement for cleanup on app shutdown.

IPC Handler

type IPCHandler interface {
    HandleIPCEvents(c *Core, msg Message) error
}

Automatically registered when using WithService.

Built-in Actions

ActionServiceStartup

type ActionServiceStartup struct{}

Sent to all services when application starts.

ActionServiceShutdown

type ActionServiceShutdown struct{}

Sent to all services when application shuts down.

Error Helpers

func E(service, operation string, err error) error

Creates a contextual error with service and operation info.

if err != nil {
    return core.E("myservice", "Connect", err)
}
// Error: myservice.Connect: connection refused

Complete Example

package main

import (
    "context"
    "github.com/Snider/Core/pkg/core"
    "github.com/Snider/Core/pkg/config"
)

type MyService struct {
    *core.ServiceRuntime[struct{}]
    data string
}

func NewMyService(c *core.Core) (any, error) {
    return &MyService{
        ServiceRuntime: core.NewServiceRuntime(c, struct{}{}),
        data:           "initialized",
    }, nil
}

func (s *MyService) OnStartup(ctx context.Context) error {
    // Startup logic
    return nil
}

func (s *MyService) OnShutdown(ctx context.Context) error {
    // Cleanup logic
    return nil
}

func (s *MyService) HandleIPCEvents(c *core.Core, msg core.Message) error {
    switch m := msg.(type) {
    case map[string]any:
        if m["action"] == "myservice.update" {
            s.data = m["data"].(string)
        }
    }
    return nil
}

func main() {
    c, err := core.New(
        core.WithService(config.Register),
        core.WithService(NewMyService),
        core.WithServiceLock(),
    )
    if err != nil {
        panic(err)
    }

    svc := core.MustServiceFor[*MyService](c, "main")
    _ = svc
}