model

package
v0.8.1 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Database added in v0.4.0

type Database interface {
	common.Service
	ORM() *gorm.DB
	DB() *sql.DB
	FromContext(ctx context.Context) *gorm.DB
	FromContextTimeout(ctx context.Context, timeout time.Duration) (*gorm.DB, context.CancelFunc)
	Cleanup(schema bool) error
	Reload() error
	// Transaction executes fn within a database transaction.
	Transaction(ctx context.Context, fn func(tctx context.Context) error, opts ...*sql.TxOptions) error
}

type MessageBus added in v0.4.1

type MessageBus interface {
	common.Service

	// Register subscribes module to the bus topic. The module receives
	// messages via MessageHandler / RawMessageHandler if it implements them.
	Register(module common.Named)

	// SendMessage publishes a typed message on the bus topic. The sender
	// does not receive its own message.
	common.MessageSender

	// SendRawMessage publishes a message with an arbitrary payload on the bus
	// topic. The sender does not receive its own message.
	common.RawMessageSender

	// NewMessenger creates a Messenger subscribed to the bus topic under the
	// given (unique) name. Use this when you need raw channel access — e.g.,
	// to bridge the bus to a WebSocket, SSE stream, or custom dispatcher.
	// The caller is responsible for calling Close on the returned Messenger.
	NewMessenger(name string) (Messenger, error)

	// AttachWebSocket pumps messages between the Messenger and the WebSocket
	// connection: outbound (bus → ws) writes each message as JSON; inbound
	// (ws → bus) decodes JSON frames and republishes them. The call blocks
	// until the connection closes and then closes the Messenger.
	AttachWebSocket(messenger Messenger, ws *websocket.Conn)
}

MessageBus is a convenience layer over Pubsub that routes every message through a single well-known topic. Modules register once and receive every message published on that topic — there are no per-topic subscriptions to manage.

Modules participate by implementing common.MessageHandler (typed dispatch) and/or common.RawMessageHandler (catch-all). The bus owns the listen loop; the underlying pubsub primitive is a pure channel transport.

type Messenger added in v0.4.1

type Messenger interface {
	common.Named

	// Ch returns the receive channel. The channel is closed by Close.
	Ch() <-chan entity.PubsubMessage

	// Send publishes a message on the bus topic with the Messenger as sender.
	// The Messenger does not receive its own message. Returns the error from
	// the underlying pubsub publish (e.g., network failure on a remote driver).
	Send(ctx context.Context, kind string, payload any) error

	// Close unsubscribes from the bus and closes the channel returned by Ch.
	Close()
}

Messenger is a subscriber handle backed by a raw pubsub channel. Unlike Register-style modules (which receive via HandleMessage / HandleRawMessage), a Messenger gives the caller direct channel access — useful for bridges (WebSocket, SSE) that need the full message record including sender identity.

type Meter added in v0.6.13

type Meter interface {
	common.Service

	// Provider returns the MeterProvider. Always non-nil, and its identity
	// never changes for the life of the process — instruments created from
	// it stay valid across service restarts, so callers create them once
	// (typically at construction) and cache them.
	Provider() metric.MeterProvider
}

Meter is the explicit metrics handle. Same doctrine as Tracer: framingo never touches the otel globals; everything that emits metrics receives this handle instead. Only the otel API types appear here — the SDK stays behind the metrics service.

type Plan added in v0.8.1

type Plan interface {
	common.Service
	// Add keeps a copy of the plan, which needs an ID, a kind, and a Task with a Schedule or
	// Manual, since a plan stays until Delete. The plan manager builds the task's Job from the
	// kind, under the plan's ID; an ID already taken on the task manager is a Conflict.
	Add(plan *entity.Plan) error
	// Trigger runs the plan now and returns the run's ID.
	// source goes on the run and on its retries and requeues; empty is an InvalidArgument.
	// The run always ends with PlanRunFinished: canceled, without a PlanRunStarted, if a
	// Cancel, Delete or Stop drops it before it starts.
	Trigger(id string, source entity.PlanRunSource) (string, error)
	// Cancel ends what the plan is doing, a run Trigger queued included, and keeps the plan.
	Cancel(id string) error
	// Delete ends what the plan is doing, forgets the plan, waits for its run to end until ctx
	// ends, and returns its latest run, nil if it has none. Its cron entry goes first, so no
	// new run starts meanwhile. Once ctx ends, what still runs is sent SignalKill, and the
	// error wraps ctx's: the run returned may then still be running, and its end comes as
	// PlanRunFinished. An ended ctx makes it a forced delete.
	Delete(ctx context.Context, id string) (*entity.PlanRun, error)
	// LastRun returns the plan's latest run, nil if it has none yet.
	LastRun(id string) (*entity.PlanRun, error)
	// OpenRunLog opens the log file of a run, by its PlanRun.LogPath, which may still be
	// being written. With tailBytes > 0 it reads from that many bytes before the end. A path
	// outside the log dir is Forbidden; no log dir or no such file is NotFound.
	OpenRunLog(path string, tailBytes int64) (io.ReadCloser, error)
	Stats(opts entity.PlanStatsOptions) ([]*entity.PlanStats, error)
}

type Pubsub

type Pubsub interface {
	common.Service

	// Publish dispatches a message to every subscriber matching topic.
	// The from string identifies the publisher and is used to skip self-delivery
	// (subscribers registered under the same name do not receive their own
	// messages). ctx applies only to cross-instance delivery (network hop on
	// the redis/kafka drivers); local fan-out runs to completion regardless,
	// so partial delivery is possible if ctx is canceled mid-publish.
	Publish(ctx context.Context, from, topic, kind string, payload any) error

	// Subscribe registers a named subscriber for the topic and returns a
	// channel that receives every matching message, including sender metadata.
	// Topics are hierarchical: subscribing to "app" receives messages from
	// "app", "app/module", "app/module/component", etc.
	// Callers must call Unsubscribe to release the subscription.
	Subscribe(name, topic string) (<-chan entity.PubsubMessage, error)

	// Unsubscribe removes a subscriber from the topic and closes its channel.
	Unsubscribe(name, topic string) error
}

Pubsub is a topic-routed message transport. It is intentionally minimal: publishers send by (from, topic, kind, payload); subscribers receive raw channels of entity.PubsubMessage. Higher-level dispatch patterns (typed handlers, registered services, websocket bridges) belong to consumers built on top — see MessageBus.

type Supervisor added in v0.4.0

type Supervisor interface {
	common.Service
	Register(services ...common.Service)
	TopoSort() error
	Services() []common.Service
	Stats() ([]*entity.SupervisorStats, error)
	// Migrate() error
	InitService(ctx context.Context, name string) error
	StartService(name string) error
	StopService(ctx context.Context, name string) error
	RestartService(ctx context.Context, name string) error
	Restart(ctx context.Context) error
}

type Task added in v0.8.1

type Task interface {
	common.Service
	// Add registers all the tasks or, if one of them cannot be, none: a task without a Job
	// is an InvalidArgument, an ID already added a Conflict.
	Add(tasks ...*entity.Task) error
	// Remove forgets the tasks and ends what they are doing, then waits for their executions
	// until ctx ends; nothing of them starts after Remove. What still runs once ctx ends is
	// sent SignalKill, like Stop, and the error wraps ctx's. A task is its job: a copy of a
	// task removes it, another task under its ID does not.
	Remove(ctx context.Context, tasks ...*entity.Task) error
	Trigger(id string, params any) error
	Cancel(id string) error
	Stats(id string) *entity.TaskStats
}

type Tracer added in v0.6.11

type Tracer interface {
	common.Service

	// Provider returns the active TracerProvider. Always non-nil: a disabled
	// or not-yet-initialized tracing service serves a noop provider, so
	// callers never nil-check and spans cost nothing when tracing is off.
	Provider() trace.TracerProvider

	// Propagator returns the context propagator used to carry trace context
	// across process boundaries (W3C tracecontext + baggage by default).
	Propagator() propagation.TextMapPropagator
}

Tracer is the explicit tracing handle. Framingo never touches the otel globals (otel.SetTracerProvider / otel.SetTextMapPropagator); everything that emits or propagates spans receives this handle instead, the same way config travels as an instance rather than the viper singleton. Only the otel API types appear here — the SDK stays behind the tracing service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL