achrix

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: MPL-2.0 Imports: 10 Imported by: 0

README

AChrix

AChrix (pronounced ATCH-riks; Persian: اَچ‌ریکس) is an AChWorks Foundation being built as a reusable, versioned application base for web-connected products. A minimal Core and optional Modules share useful engineering capabilities while products own their business behavior.

The accepted starting stack is Go and ordinary PostgreSQL. Optional infrastructure is introduced for real workloads; see ADR-0002 and ADR-0003.

Start here

Implementation status

The initial executable baseline supplies minimal instance-owned Go composition, authorization and lifecycle contracts. The separately composed Notes consumer proves a pinned dependency, consumer-owned PostgreSQL persistence/migrations, direct invocation and one HTTP adapter through the same Application policy. Operations owns the supported matrix and the shared local/CI validation command. Issue #1 owns full executable acceptance and its exact evidence; this fixture does not establish a production product/deployment profile.

Suitable products will consume a versioned AChrix dependency rather than permanently copy its shared source. Product-specific behavior stays with the product. Koinon owns ecosystem governance/discovery and is not an AChrix runtime dependency.

Consume and extend

For a new product, pin the reviewed v0.3 developer source release from your own Go module. GitHub Releases owns actual availability and exact artifact evidence:

go get github.com/AChWorks/achrix@v0.3.0

The product quick start supplies a complete runnable Core example, selective Module entry points, installation and upgrade steps. Compose through public contracts; products own their account/profile meaning, permission policy, domain/business semantics and data. Keep custom product source in the product and update AChrix as a normal reviewed dependency. Internationalization owns multilingual and RTL/LTR evolution.

The v0.3.0 source line is the next pre-v1 developer minor after immutable v0.2.0. It retains Core authorization ABI 2 and the established Core/Identity/Audit/Media/Admin contracts while adding the optional Multi-Site resolver, bounded Module resource configuration, explicit private SVG/schema3 support and separately authorized clean PNG/JPEG preparation. Existing v0.2 consumers must read the v0.2 to v0.3 migration; published v0.1/v0.2 tags and their recorded compatibility remain immutable.

That line includes product-local Identity accounts, maintained Argon2id passwords and revocable server-side sessions with a same-origin HTTPS cookie/CSRF adapter. Audit records the five accountable account/credential/status/revocation operations in the same PostgreSQL transaction, with authorized bounded query/export. The independent Notes test composition proves authentication followed by separate product authorization and retained-dataset restore; it establishes no production deployment, CMS, central identity service or permission roles.

It also includes a private Media file library: PNG/JPEG by default, with explicit opt-in to a finite common attachment profile, separately authorized create/list/read/conditional-delete operations and bounded explicit reconciliation. It uses real PostgreSQL metadata and private Linux filesystem storage; products own permissions, content relationships, ingress and their production recovery profile. The v0.3.0 line adds separately selected private SVG with schema version 3 and separately authorized clean PNG/JPEG preparation; published v0.2.0 cannot interpret the newer Media ledger. The independent consumer proves trusted HTTPS and coherent quiesced metadata plus asset restore.

The Admin shell composes real Identity-owned and Media-owned screens through their public services. Products own explicit grants and HTTPS ingress; the shell supplies bounded presentation, navigation, English/Persian direction and safe form feedback. Its independent trusted-TLS browser proof covers both real surfaces without copying Foundation source or adding a frontend framework.

Licensing and participation

First-party repository content defaults to MPL-2.0. Compatible independent commercial/third-party Modules are possible; any Apache-2.0 SDK designation requires an explicit artifact scope. Licensing owns the details.

Governance, Trademark Policy and the Contribution Agreement cover canonical authority, honest representation and incoming rights. Publishing the agreement or opening a PR does not constitute signed consent.

Documentation

Overview

Package achrix supplies instance-owned composition, authorization and lifecycle for trusted, compiled modules. It owns no product data or authentication scheme.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrDenied                   = errors.New("permission denied")
	ErrAuthorizationUnavailable = errors.New("authorization unavailable")
	ErrNotReady                 = errors.New("application not ready")
	ErrComposition              = errors.New("invalid composition")
)

Functions

func Version 

func Version() string

Version identifies the actual source-backed Foundation dependency in a consumer. Local unversioned builds explicitly report development; no release is invented.

Types

type Application 

type Application struct {
	// contains filtered or unexported fields
}

Application is immutable after composition except for lifecycle/admission state. Domain methods remain typed consumer-owned methods, not an untyped dispatcher.

func New 

func New(config Config, policy Policy, modules ...Module) (*Application, error)

New rejects duplicate, missing, incompatible or cyclic composed contracts before any module starts. Module descriptors are snapshotted to prevent mutable registry state leaking between instances. No process-global registration exists.

func (*Application) Authorize 

func (a *Application) Authorize(ctx context.Context, p Principal, capability, resource string) error

Authorize fails closed for empty principals, unknown capabilities, stopped applications or policy errors. Call it inside the owning Application operation before authorization-sensitive reads/writes; transport discovery grants no rights. resource is a product-owned opaque scope/reference, not trusted client claims. Callers must supply a deadline. Shutdown cancels/drains admitted policy work; calls outside ready return ErrNotReady without invoking policy. Policy errors never expose raw provider text: only explicit ErrDenied is a permission denial. Core emits safe DEBUG detail; the product owns bounded denial/failure visibility.

func (*Application) Components 

func (a *Application) Components() []Descriptor

Components returns a defensive snapshot for compatible build/recovery identity.

func (*Application) Ready 

func (a *Application) Ready(ctx context.Context) error

Ready checks only composed local dependencies, under the caller's deadline. It never waits behind lifecycle callbacks and is canceled/drained by Shutdown. Repeated probe detail is DEBUG; the product owns bounded operational signals.

func (*Application) Shutdown 

func (a *Application) Shutdown(parent context.Context) error

Shutdown closes admission immediately, cancels admitted Ready/Authorize work, drains it, then stops Modules in reverse order. Its deadline covers lifecycle waiting, drain and Stop together. If waiting/drain expires, the instance remains stopping and a later Shutdown may finish cleanup; Stop never races callbacks. Completed cleanup is not repeated and its result is retained. Modules must terminate their owned domain work in Stop; Core tracks only its own callbacks.

func (*Application) Start 

func (a *Application) Start(parent context.Context) error

Start is a one-shot operation. A failed start cleans the failing module and all earlier modules in reverse order using a fresh bounded cleanup context. Lifecycle failures are diagnosed by component and phase without logging extension errors.

type Capability 

type Capability struct {
	ID      string
	Version uint32
}

Capability identifies an owned public contract. Version is its positive ABI revision, not the implementation's release version. Compatible additive changes retain the revision; incompatible contracts increment it. Composition matches exact revisions and admits only one provider/revision for each capability ID.

type Config 

type Config struct {
	// Timeouts bound the whole lifecycle phase, including all participating modules.
	StartupTimeout  time.Duration
	ShutdownTimeout time.Duration
	Logger          *slog.Logger
}

type Descriptor 

type Descriptor struct {
	ID string

	// Version identifies the Module implementation's packaged source dependency.
	// Official packages in this Go module use Version(); capability ABI is separate.
	Version  string
	Provides []Capability
	Requires []Capability
	Optional []Capability
}

Descriptor is deterministic, side-effect-free, cheap composition metadata. Describing a Module must not read environment/secrets, acquire resources, call networks/databases or mutate registration. Optional providers may be absent; when present they must match the exact revision and precede their consumers.

type Module 

type Module interface {
	Descriptor() Descriptor
	Start(context.Context) error
	Ready(context.Context) error
	Stop(context.Context) error
}

Module owns its resources. Start, Ready and Stop must honor context cancellation. Stop must clean resources acquired by a partially failed Start and be safe when Start acquired none. In-process code is trusted; contexts are not a sandbox.

type Policy 

type Policy interface {
	Authorize(context.Context, Principal, string, string) error
}

Policy is the consumer-owned authorization decision: nil allows, ErrDenied (possibly wrapped) explicitly denies, and other errors fail closed as evaluation unavailable. It must honor cancellation and must not mutate domain state. Implementations must be safe for concurrent calls.

type PolicyFunc 

type PolicyFunc func(context.Context, Principal, string, string) error

func (PolicyFunc) Authorize 

func (f PolicyFunc) Authorize(ctx context.Context, p Principal, c, r string) error

type Principal 

type Principal string

Principal is a product-authenticated opaque identity, never a bearer token.

Source Files

View all Source files

Directories

Path Synopsis
SPDX-License-Identifier: MPL-2.0 Package admin composes trusted, compiled Module-owned administration screens.
 SPDX-License-Identifier: MPL-2.0 Package admin composes trusted, compiled Module-owned administration screens.
SPDX-License-Identifier: MPL-2.0 Package audit owns retained accountability records.
 SPDX-License-Identifier: MPL-2.0 Package audit owns retained accountability records.
SPDX-License-Identifier: MPL-2.0
 SPDX-License-Identifier: MPL-2.0
admin
SPDX-License-Identifier: MPL-2.0 Package admin owns Identity's account-management presentation.
 SPDX-License-Identifier: MPL-2.0 Package admin owns Identity's account-management presentation.
SPDX-License-Identifier: MPL-2.0
 SPDX-License-Identifier: MPL-2.0
admin
SPDX-License-Identifier: MPL-2.0 Package admin owns Media's private file-library presentation.
 SPDX-License-Identifier: MPL-2.0 Package admin owns Media's private file-library presentation.
Package multisite resolves an authorized exact authority to a stable site ID.
 Package multisite resolves an authorized exact authority to a stable site ID.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.