kosmos

README

Kosmos-Go

Kosmos-Go is a Go-based framework and data persistence layer built around MongoDB.

The Microcosm Philosophy

The naming strategy in kosmos-go treats the database as foundational space for where the application exists.

Foundational Terminology

• Collapse / Collapsable: The transition from potential to actual state. Used for resolving entity IDs, establishing timestamps, and pulling secrets into tangible values.
• Witness / Observer: The act of fixing an entity's state into empirical reality. An Observer interacts with MongoDB, and to Witness means to persist a specific state.
• Ripple: Causal side-effects extending outwards from an event (used for defining hooks or secondary reactive operations alongside a Witness or Collapse).
• Entangled: A state of being linked to the fabric of reality (i.e., whether an entity currently exists with an ID in the database).
• Summon: Calling forth an authoritative entity, factory, or singleton (e.g., SummonSecretManager, SummonMongo).
• Coalesce: Merging unformed configuration data, environment variables, and connections into a unified single source of truth.
• Ether: The ambient layer handling environment variables, configuration streams, and secrets.
• Detectable: Interfaces representing objects that can be witnessed, filtered, or tracked.

Architecture & Packages

kosmos

The top-level package that exposes the core capabilities:

• Setting up the ambient environment via Ignite and IgniteBase.
• The data representation layer with kosmos.BaseModel. Models embedded with kosmos.BaseModel gain database capabilities via a custom struct tag (kosmos:"branch>collection" or kosmos:"collection").
• Operations: Use commands like kosmos.Detect, kosmos.Witness, and kosmos.All to manipulate your data.
• Lifecycle: As a model's state converges, the BaseModel automatically defines fields like _id, updated_time, and created_time under Collapse() events.

observation

The data connectivity layer bridging the application to MongoDB.

• EntityObserver & EntityDetector: Used internally by kosmos.Witness and kosmos.Detect to interact with collections.
• MongoDataverse: Maintains robust pooling and connections with different PurposeAffinity roles (e.g., Admin, Creator, Observer), allowing specialized access rights.
• Supports administrative commands, proxy connections, and replica set status management.

ether

The foundational configuration and secrets manager.

• Integrates with Google Secret Manager (cloud.google.com/go/secretmanager) and viper/cobra for command-line flags and environment variables.
• Uses Liminal interfaces to manage configuration structures securely.
• Evaluates raw URI strings and secrets dynamically, allowing credentials to be injected transparently into connections without hardcoding.

Getting Started

1. Initialize your environment by calling kosmos.Ignite or kosmos.IgniteBase, which will load environment variables and secrets via the ether package.
2. Initialize models by embedding kosmos.BaseModel as the first field and assigning the kosmos struct tag to map to a branch and collection.

type MyModel struct {
    kosmos.BaseModel `bson:",inline" kosmos:"my_branch>my_collection"`
    Name string `bson:"name"`
}

1. Begin Witnessing and Detecting reality!

obj := &MyModel{Name: "Hello World"}
err := kosmos.Witness(ctx, obj)

Documentation

Index

• Constants
• func All[T matter.Detectable]() *matter.Detector[T]
• func CollapseSecretString(s string) (string, error)
• func Detect[T matter.Detectable](filters ...expression.QueryFieldPredicate) *matter.Detector[T]
• func Fld(name string) matter.EntityField
• func Ignite(cmdSource *cobra.Command, source ...string)
• func IgniteBase(cmdSource *cobra.Command, source ...string)
• func IsSecretSourceFormat(s string) bool
• func MustHaveObserverClient() *mongo.Client
• func Record[C matter.Collapsible](ctx context.Context, obj C) error
• func SummonObservationFor(purpose matter.PurposeAffinity) *matter.MongoDataverse
• func SummonSecretManager() ether.SecretManager
• type BaseModel
  • func (e *BaseModel) Collapse() matter.Ripple
  • func (e *BaseModel) CollapseID() bson.ObjectID
  • func (e *BaseModel) Decohere(ripple matter.Ripple) error
  • func (e BaseModel) GetID() bson.ObjectID
  • func (e BaseModel) HasID() bool
  • func (e BaseModel) LastObserved() time.Time
  • func (e BaseModel) SelfScope() expression.Scope

Constants

const (
	ModelState_Unset int32 = iota
	ModelState_Transition
	ModelState_Material
)

Functions

func All

func All[T matter.Detectable]() *matter.Detector[T]

func CollapseSecretString

func CollapseSecretString(s string) (string, error)

func Detect

func Detect[T matter.Detectable](filters ...expression.QueryFieldPredicate) *matter.Detector[T]

func Fld

func Fld(name string) matter.EntityField

func Ignite

func Ignite(cmdSource *cobra.Command, source ...string)

Ignite the kosmos. A chain of events that materialize into existence an environment. Failure to do so will be fatal to the application. An application cannot exist without the kosmos.

func IgniteBase

func IgniteBase(cmdSource *cobra.Command, source ...string)

Ignite Base the kosmos where Secret Manager is optional and no Observer Client is created. Failure to do so will be fatal to the application. An application cannot exist without the kosmos.

func IsSecretSourceFormat

func IsSecretSourceFormat(s string) bool

func MustHaveObserverClient

func MustHaveObserverClient() *mongo.Client

func Record

func Record[C matter.Collapsible](ctx context.Context, obj C) error

func SummonObservationFor

func SummonObservationFor(purpose matter.PurposeAffinity) *matter.MongoDataverse

func SummonSecretManager

func SummonSecretManager() ether.SecretManager

Types

type BaseModel

type BaseModel struct {
	ID          bson.ObjectID `xml:"id,attr" json:"ID" bson:"_id,omitempty"`
	UpdatedTime time.Time     `xml:"updated" json:"updated" bson:"updated_time"`
	CreatedTime *time.Time    `xml:"created" json:"created" bson:"created_time,omitempty"`
	// contains filtered or unexported fields
}

Usage Embed BaseModel to your model struct as the first field with a kosmos tag Example: kosmos.BaseModel `bson:",inline" kosmos:"pieriansea>page"`

func (*BaseModel) Collapse

func (e *BaseModel) Collapse() matter.Ripple

func (*BaseModel) CollapseID

func (e *BaseModel) CollapseID() bson.ObjectID

func (*BaseModel) Decohere

func (e *BaseModel) Decohere(ripple matter.Ripple) error

func (BaseModel) GetID

func (e BaseModel) GetID() bson.ObjectID

func (BaseModel) HasID

func (e BaseModel) HasID() bool

func (BaseModel) LastObserved

func (e BaseModel) LastObserved() time.Time

func (BaseModel) SelfScope

func (e BaseModel) SelfScope() expression.Scope