astraengine

package module
v2.0.2 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: GPL-3.0 Imports: 6 Imported by: 0

README

AstraEngine

AstraEngine is a Go framework for bots and community automation that keeps application logic independent from Telegram, VK and Discord SDKs.

The current v2 runtime provides:

  • command, callback, message, regex and typed-event routing;
  • middleware, groups, rate limiting and conversational state;
  • normalized events, replies, edits, private delivery, keyboards and attachments;
  • Telegram, VK and Discord adapters with native SDK escape hatches;
  • plugin lifecycle, migrations, validated settings and optional Admin extensions;
  • memory and PostgreSQL storage;
  • structured logging, panic recovery, adapter retry and graceful shutdown;
  • an optional Admin backend with RBAC, sessions, audit/log streams, declarative UI metadata, Control WebSocket and durable operations.

Install

go get github.com/andrewkydev/astraengine/v2@latest

Use the Go version declared in go.mod.

Minimal bot

package main

import (
	"context"
	"os"
	"os/signal"
	"syscall"

	astraengine "github.com/andrewkydev/astraengine/v2"
	botctx "github.com/andrewkydev/astraengine/v2/core/context"
	"github.com/andrewkydev/astraengine/v2/platform/telegram"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	app := astraengine.New("example")
	app.Platform(telegram.New(telegram.Config{Token: os.Getenv("TELEGRAM_TOKEN")}))
	app.Command("start", func(ctx *botctx.Context) error {
		return ctx.SendText("Hello from AstraEngine")
	})

	if err := app.Start(ctx); err != nil && err != context.Canceled {
		panic(err)
	}
}

Never commit platform tokens. Load them from the environment or use the validated loader in configs/runtime.

Main packages

Package Purpose
core/app, core/router, core/context Runtime, routing and handler context
core/event, keyboard, payload, attachments Portable messaging contracts
state, core/fsm Conversational state; state remains the compatibility scenes API
platform/telegram, platform/vk, platform/discord SDK adapters and native escape hatches
plugin, plugins Compile-time modules, migrations and settings
storage/memory, storage/postgres Standard persistence implementations
admin/* Optional management API, authentication, control and operations
runtime, logging, configs/runtime Process helpers, diagnostics and configuration

The core never imports platform SDKs. Platform-specific behavior stays in adapters and is available through Raw or typed From helpers when it is not genuinely portable.

Platform status

  • Telegram and VK cover the primary portable messaging flow.
  • Discord supports messages, slash commands, interactions, buttons, embeds, files, replies, edits and private responses. Moderation/role management and full live parity are still incomplete.
  • Redis, payments, cluster queues, WASM plugins and additional adapters are not completed framework features.

Documentation

Runnable examples live in examples/. The Admin frontend and its demo application are maintained as separate repositories.

License

GPLv3. See LICENSE.

Documentation

Overview

Package astraengine exposes the public convenience API for building bots and automation apps on top of the AstraEngine runtime.

Most concrete implementations still live in subpackages such as core/app, platform/telegram, storage/postgres and plugin. The root package intentionally stays small so application code can start from astraengine.New while importing only the adapters and storage backends it actually needs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App 

type App = app.App

App is the main AstraEngine runtime type.

func New 

func New(name string) *App

New creates a new AstraEngine app runtime.

type Cache 

type Cache = cache.Cache

Cache is the engine cache contract.

type Group 

type Group = app.Group

Group is a route group with its own middleware chain.

type Handler 

type Handler = middleware.Handler

Handler processes a single normalized engine event.

type Middleware 

type Middleware = middleware.Middleware

Middleware wraps a Handler with cross-cutting behavior.

type Platform 

type Platform = platform.Platform

Platform is implemented by concrete adapters such as Telegram, VK and Discord.

type Plugin 

type Plugin = plugin.Plugin

Plugin is the engine plugin contract.

type Store 

type Store = storage.Store

Store is the engine storage contract.

Source Files

View all Source files

Directories

Path Synopsis
Package admin exposes convenient constructors for the extensible Admin API.
 Package admin exposes convenient constructors for the extensible Admin API.
api
Package api provides the extensible HTTP Admin API server.
 Package api provides the extensible HTTP Admin API server.
auth
Package auth defines Admin API authentication claims and verification.
 Package auth defines Admin API authentication claims and verification.
control
Package control implements Astra Admin Control WebSocket protocol v1.
 Package control implements Astra Admin Control WebSocket protocol v1.
login
observability
Package observability records handler events, audits and basic runtime metrics.
 Package observability records handler events, audits and basic runtime metrics.
operations
resources
Package resources defines declarative Admin API resource metadata.
 Package resources defines declarative Admin API resource metadata.
ui
Package ui defines the declarative Astra Admin UI protocol.
 Package ui defines the declarative Astra Admin UI protocol.
Package attachments provides a shared attachment model and lightweight helpers.
 Package attachments provides a shared attachment model and lightweight helpers.
Package cache defines the storage-independent cache contract used by the engine.
 Package cache defines the storage-independent cache contract used by the engine.
memory
Package memory implements an in-process cache for tests and single-instance bots.
 Package memory implements an in-process cache for tests and single-instance bots.
nop
Package nop implements a cache that never stores values.
 Package nop implements a cache that never stores values.
cmd
astrabot command
configs
runtime
Package runtime loads example and CLI configuration from environment variables.
 Package runtime loads example and CLI configuration from environment variables.
core
app
Package app wires platforms, routing, middleware, plugins and storage into a runtime.
 Package app wires platforms, routing, middleware, plugins and storage into a runtime.
botcmd
Package botcmd parses commands and provides alias-aware command middleware.
 Package botcmd parses commands and provides alias-aware command middleware.
capability
Package capability describes optional features supported by platform adapters.
 Package capability describes optional features supported by platform adapters.
command
Package command contains shared command parsing for platform adapters.
 Package command contains shared command parsing for platform adapters.
context
Package context provides the handler context and cross-platform message helpers.
 Package context provides the handler context and cross-platform message helpers.
errors
Package errors defines machine-readable AstraEngine errors.
 Package errors defines machine-readable AstraEngine errors.
event
Package event contains the platform-neutral event model dispatched by AstraEngine.
 Package event contains the platform-neutral event model dispatched by AstraEngine.
fsm
Package fsm provides lightweight mode-and-step state injection.
 Package fsm provides lightweight mode-and-step state injection.
middleware
Package middleware defines handlers and composable event middleware.
 Package middleware defines handlers and composable event middleware.
platform
Package platform defines adapter contracts and platform-neutral outbound messages.
 Package platform defines adapter contracts and platform-neutral outbound messages.
ratelimit
Package ratelimit provides in-memory fixed-window limits and routing middleware.
 Package ratelimit provides in-memory fixed-window limits and routing middleware.
router
Package router dispatches commands, callbacks and text events to handlers.
 Package router dispatches commands, callbacks and text events to handlers.
examples
echo-bot command
multi-platform command
multi-platform/commands
Package input normalizes message, command and callback input for handlers.
 Package input normalizes message, command and callback input for handlers.
Package keyboard builds platform-neutral inline and reply keyboards.
 Package keyboard builds platform-neutral inline and reply keyboards.
Package logging configures the standard library's structured slog logger.
 Package logging configures the standard library's structured slog logger.
Package mentions extracts common Telegram, VK and Discord mention formats.
 Package mentions extracts common Telegram, VK and Discord mention formats.
Package navigation provides callback-based pagination helpers.
 Package navigation provides callback-based pagination helpers.
Package payload encodes portable callback button data.
 Package payload encodes portable callback button data.
platform
discord
Package discord provides the experimental Discord adapter.
 Package discord provides the experimental Discord adapter.
telegram
Package telegram implements AstraEngine's Telegram Bot API adapter.
 Package telegram implements AstraEngine's Telegram Bot API adapter.
vk
Package vk implements AstraEngine's VK community bot adapter.
 Package vk implements AstraEngine's VK community bot adapter.
Package plugin implements compile-time plugins, settings and migration metadata.
 Package plugin implements compile-time plugins, settings and migration metadata.
plugins
auth
Package auth contains the baseline compile-time auth plugin.
 Package auth contains the baseline compile-time auth plugin.
broadcast
Package broadcast contains the baseline compile-time broadcast plugin.
 Package broadcast contains the baseline compile-time broadcast plugin.
roles
Package roles contains the baseline compile-time roles plugin.
 Package roles contains the baseline compile-time roles plugin.
Package runtime contains optional lifecycle, scheduling and worker helpers.
 Package runtime contains optional lifecycle, scheduling and worker helpers.
Package state provides persistent sessions and conversational FSM scenes.
 Package state provides persistent sessions and conversational FSM scenes.
Package storage defines persistent models and repository contracts.
 Package storage defines persistent models and repository contracts.
memory
Package memory implements process-local AstraEngine repositories.
 Package memory implements process-local AstraEngine repositories.
postgres
Package postgres implements AstraEngine repositories using pgx and PostgreSQL.
 Package postgres implements AstraEngine repositories using pgx and PostgreSQL.

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.