README
¶
Core
NOTICE The current version here is not the current version, which is in letheanVPN/desktop/services/core (from memory). This was a nice idea, but I'm reorganising the code bases. Check back later.
Core is a Web3 Framework, written in Go using Wails.io to replace Electron and the bloat of browsers that, at their core, still live in their mum's basement.
More to come, follow us on Discord http://discord.dappco.re
Repo: https://github.com/Snider/Core
Quick start
import core "github.com/Snider/Core"
app := core.New(
core.WithServiceLock(),
)
Development Workflow
This project follows a Test-Driven Development (TDD) approach. We use Task for task automation to streamline the development process.
The recommended workflow is:
-
Generate Tests: For any changes to the public API, first generate the necessary test stubs.
task test-gen -
Run Tests (and watch them fail): Verify that the new tests fail as expected.
task test -
Implement Your Feature: Write the code to make the tests pass.
-
Run Tests Again: Ensure all tests now pass.
task test -
Submit for Review: Once your changes are complete and tests are passing, submit them for a CodeRabbit review.
task review
Project Structure
The project is organized into the following main directories:
pkg/: Contains the core Go packages that make up the framework.cmd/: Contains the entry points for the two main applications:core-gui/: The Wails-based GUI application.core/: The command-line interface (CLI) application.
Prerequisites
Building and Running
GUI Application
To run the GUI application in development mode:
task gui:dev
To build the final application for your platform:
task gui:build
CLI Application
To build the CLI application:
task cli:build
The executable will be located in the cmd/core/bin directory.
Available Tasks
To run any of the following tasks, open your terminal in the project's root directory and execute the task command.
General Tasks
task test: Runs all Go tests recursively for the entire project.task test-gen: Generates tests for the public API.task check: A comprehensive check that runsgo mod tidy, the full test suite, and a CodeRabbit review.task review: Submits the current changes for a CodeRabbit review.task cov: Generates a test coverage profile (coverage.txt).task cov-view: Opens the HTML coverage report in your browser.task sync: Updates the public API Go files to match the exported interface of the modules.
GUI Application (cmd/core-gui)
These tasks are run from the root directory and operate on the GUI application.
task gui:build: Builds the GUI application.task gui:package: Packages a production build of the GUI application.task gui:run: Runs the GUI application.task gui:dev: Runs the GUI application in development mode, with hot-reloading enabled.
CLI Application (cmd/core)
These tasks are run from the root directory and operate on the CLI application.
task cli:build: Builds the CLI application.task cli:build:dev: Builds the CLI application for development.task cli:run: Builds and runs the CLI application.task cli:sync: Updates the public API Go files.task cli:test-gen: Generates tests for the public API.
Docs (MkDocs)
The documentation site is powered by MkDocs Material and lives under docs/ with configuration in mkdocs.yml.
- Install docs tooling:
pip install -r docs/requirements.txt
- Live preview from repository root:
mkdocs serve -o -c
- Build static site:
mkdocs build --clean
Releasing (GoReleaser)
This repo includes a minimal GoReleaser config (.goreleaser.yaml). Tagged pushes like v1.2.3 will build and publish archives via GitHub Actions (see .github/workflows/release.yml).
- Local dry run:
goreleaser release --snapshot --clean - Real release: create and push a version tag
vX.Y.Z.
Go Workspaces
This repository uses Go workspaces (go.work) targeting Go 1.25.
- Add/remove modules with
go work use. - Typical workflow:
go work syncgo mod tidyin modules as needed
Documentation
¶
Overview ¶
Package e provides a standardized error handling mechanism for the Core library. It allows for wrapping errors with contextual information, making it easier to trace the origin of an error and provide meaningful feedback.
The design of this package is influenced by the need for a simple, yet powerful way to handle errors that can occur in different layers of the application, from low-level file operations to high-level service interactions.
The key features of this package are:
- Error wrapping: The Op and an optional Msg field provide context about where and why an error occurred.
- Stack traces: By wrapping errors, we can build a logical stack trace that is more informative than a raw stack trace.
- Consistent error handling: Encourages a uniform approach to error handling across the entire codebase.
Index ¶
- func App() *application.App
- func E(op, msg string, err error) error
- func MustServiceFor[T any](c *Core, name string) T
- func ServiceFor[T any](c *Core, name string) (T, error)
- type ActionDisplayOpenWindow
- type ActionServiceShutdown
- type ActionServiceStartup
- type Config
- type Contract
- type Core
- func (c *Core) ACTION(msg Message) error
- func (c *Core) Assets() embed.FS
- func (c *Core) Config() Config
- func (c *Core) Core() *Core
- func (c *Core) Display() Display
- func (c *Core) RegisterAction(handler func(*Core, Message) error)
- func (c *Core) RegisterActions(handlers ...func(*Core, Message) error)
- func (c *Core) RegisterService(name string, api any) error
- func (c *Core) Service(name string) any
- func (c *Core) ServiceShutdown(ctx context.Context) error
- func (c *Core) ServiceStartup(ctx context.Context, options application.ServiceOptions) error
- type Crypt
- type Display
- type Error
- type Features
- type Help
- type I18n
- type Message
- type Option
- type Runtime
- type ServiceFactory
- type ServiceRuntime
- type WindowConfig
- type WindowOption
- type Workspace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func App ¶
func App() *application.App
App returns the global application instance. It panics if the Core has not been initialized.
func E ¶
E is a helper function to create a new Error. This is the primary way to create errors that will be consumed by the system. For example:
return e.E("config.Load", "failed to load config file", err)
The 'op' parameter should be in the format of 'package.function' or 'service.method'. The 'msg' parameter should be a human-readable message that can be displayed to the user. The 'err' parameter is the underlying error that is being wrapped.
func MustServiceFor ¶
MustServiceFor retrieves a registered service by name and asserts its type to the given interface T. It panics if the service is not found or cannot be cast to T.
Types ¶
type ActionDisplayOpenWindow ¶
type ActionDisplayOpenWindow struct {
Name string
Options application.WebviewWindowOptions
}
ActionDisplayOpenWindow is a structured message for requesting a new window.
type ActionServiceShutdown ¶
type ActionServiceShutdown struct{}
ActionServiceShutdown is a message sent when the application is shutting down. This allows services to perform cleanup tasks, such as saving state or closing resources.
type ActionServiceStartup ¶
type ActionServiceStartup struct{}
ActionServiceStartup is a message sent when the application's services are starting up. This provides a hook for services to perform initialization tasks.
type Config ¶
type Config interface {
// Get retrieves a configuration value by key and stores it in the 'out' variable.
Get(key string, out any) error
// Set stores a configuration value by key.
Set(key string, v any) error
}
Config provides access to application configuration.
type Contract ¶
type Contract struct {
// DontPanic, if true, instructs the Core to recover from panics and return an error instead.
DontPanic bool
// DisableLogging, if true, disables all logging from the Core and its services.
DisableLogging bool
}
Contract specifies the operational guarantees that the Core and its services must adhere to. This is used for configuring panic handling and other resilience features.
type Core ¶
type Core struct {
App *application.App
Features *Features
// contains filtered or unexported fields
}
Core is the central application object that manages services, assets, and communication.
func New ¶
New initialises a Core instance using the provided options and performs the necessary setup. It is the primary entry point for creating a new Core application.
Example:
core, err := core.New(
core.WithService(&MyService{}),
core.WithAssets(assets),
)
func (*Core) ACTION ¶
ACTION dispatches a message to all registered IPC handlers. This is the primary mechanism for services to communicate with each other.
func (*Core) RegisterAction ¶
RegisterAction adds a new IPC handler to the Core.
func (*Core) RegisterActions ¶
RegisterActions adds multiple IPC handlers to the Core.
func (*Core) RegisterService ¶
RegisterService adds a new service to the Core.
func (*Core) Service ¶
Service retrieves a registered service by name. It returns nil if the service is not found.
func (*Core) ServiceShutdown ¶
ServiceShutdown is the entry point for the Core service's shutdown lifecycle. It is called by Wails when the application shuts down.
func (*Core) ServiceStartup ¶
func (c *Core) ServiceStartup(ctx context.Context, options application.ServiceOptions) error
ServiceStartup is the entry point for the Core service's startup lifecycle. It is called by Wails when the application starts.
type Crypt ¶
type Crypt interface {
// EncryptPGP encrypts data using PGP and writes the result to the given writer.
EncryptPGP(writer io.Writer, recipientPath, data string, signerPath, signerPassphrase *string) (string, error)
// DecryptPGP decrypts a PGP message.
DecryptPGP(recipientPath, message, passphrase string, signerPath *string) (string, error)
}
Crypt provides cryptographic functions.
type Display ¶
type Display interface {
// OpenWindow creates and displays a new window with the given options.
OpenWindow(opts ...WindowOption) error
}
Display manages windows and UI.
type Error ¶
type Error struct {
// Op is the operation being performed, e.g., "config.Load".
Op string
// Msg is a human-readable message explaining the error.
Msg string
// Err is the underlying error that was wrapped.
Err error
}
Error represents a standardized error with operational context.
type Features ¶
type Features struct {
// Flags is a list of enabled feature flags.
Flags []string
}
Features provides a way to check if a feature is enabled. This is used for feature flagging and conditional logic.
type Help ¶
type Help interface {
// Show displays the main help topic.
Show() error
// ShowAt displays the help topic for the given anchor.
ShowAt(anchor string) error
}
Help manages the in-app documentation and help system.
type I18n ¶
type I18n interface {
// Translate returns the translated string for the given key.
Translate(key string) string
// SetLanguage changes the active language.
SetLanguage(lang string) error
}
I18n provides internationalization and localization services.
type Message ¶
type Message interface{}
Message is the interface for all messages that can be sent through the Core's IPC system. Any struct can be a message, allowing for structured data to be passed between services.
type Option ¶
Option is a function that configures the Core. This is used to apply settings and register services during initialization.
func WithAssets ¶
WithAssets creates an Option that registers the application's embedded assets. This is necessary for the application to be able to serve its frontend.
func WithName ¶
WithName creates an option that registers a service with a specific name. This is useful when the service name cannot be inferred from the package path, such as when using anonymous functions as factories. Note: Unlike WithService, this does not automatically discover or register IPC handlers. If your service needs IPC handling, implement HandleIPCEvents and register it manually.
func WithService ¶
WithService creates an Option that registers a service. It automatically discovers the service name from its package path and registers its IPC handler if it implements a method named `HandleIPCEvents`.
Example:
// In myapp/services/calculator.go
package services
type Calculator struct{}
func (s *Calculator) Add(a, b int) int { return a + b }
// In main.go
import "myapp/services"
core.New(core.WithService(services.NewCalculator))
func WithServiceLock ¶
func WithServiceLock() Option
WithServiceLock creates an Option that prevents any further services from being registered after the Core has been initialized. This is a security measure to prevent late-binding of services that could have unintended consequences.
func WithWails ¶
func WithWails(app *application.App) Option
WithWails creates an Option that injects the Wails application instance into the Core. This is essential for services that need to interact with the Wails runtime.
type Runtime ¶
type Runtime struct {
Core *Core
// contains filtered or unexported fields
}
Runtime is the container that holds all instantiated services. Its fields are the concrete types, allowing Wails to bind them directly. This struct is the primary entry point for the Wails application.
func NewRuntime ¶
func NewRuntime(app *application.App) (*Runtime, error)
NewRuntime creates and wires together all application services. This is the simplest way to create a new Runtime, but it does not allow for the registration of any custom services.
func NewWithFactories ¶
func NewWithFactories(app *application.App, factories map[string]ServiceFactory) (*Runtime, error)
NewWithFactories creates a new Runtime instance using the provided service factories. This is the most flexible way to create a new Runtime, as it allows for the registration of any number of services.
func (*Runtime) ServiceName ¶
ServiceName returns the name of the service. This is used by Wails to identify the service.
func (*Runtime) ServiceShutdown ¶
ServiceShutdown is called by Wails at application shutdown. This is where the Core's shutdown lifecycle is initiated.
func (*Runtime) ServiceStartup ¶
func (r *Runtime) ServiceStartup(ctx context.Context, options application.ServiceOptions)
ServiceStartup is called by Wails at application startup. This is where the Core's startup lifecycle is initiated.
type ServiceFactory ¶
ServiceFactory defines a function that creates a service instance. This is used to decouple the service creation from the runtime initialization.
type ServiceRuntime ¶
type ServiceRuntime[T any] struct { // contains filtered or unexported fields }
ServiceRuntime is a helper struct embedded in services to provide access to the core application. It is generic and can be parameterized with a service-specific options struct.
func NewServiceRuntime ¶
func NewServiceRuntime[T any](c *Core, opts T) *ServiceRuntime[T]
NewServiceRuntime creates a new ServiceRuntime instance for a service. This is typically called by a service's constructor.
func (*ServiceRuntime[T]) Config ¶
func (r *ServiceRuntime[T]) Config() Config
Config returns the registered Config service from the core application. This is a convenience method for accessing the application's configuration.
func (*ServiceRuntime[T]) Core ¶
func (r *ServiceRuntime[T]) Core() *Core
Core returns the central core instance, providing access to all registered services.
type WindowConfig ¶
type WindowConfig struct {
Name string
Title string
URL string
Width int
Height int // Add other common window options here as needed
}
WindowConfig represents the configuration for a window.
type WindowOption ¶
type WindowOption interface {
// Apply applies the window option to the given configuration.
Apply(*WindowConfig)
}
WindowOption configures window creation.
type Workspace ¶
type Workspace interface {
// CreateWorkspace creates a new workspace with the given identifier and password.
CreateWorkspace(identifier, password string) (string, error)
// SwitchWorkspace changes the active workspace.
SwitchWorkspace(name string) error
// WorkspaceFileGet retrieves the content of a file from the current workspace.
WorkspaceFileGet(filename string) (string, error)
// WorkspaceFileSet writes content to a file in the current workspace.
WorkspaceFileSet(filename, content string) error
}
Workspace manages user workspaces.
Source Files
Directories