webapi

Documentation

Overview

Package webapi provides a web API spam detection service.

Index

• func CSRFTokenMiddleware(next http.Handler) http.Handler
• func GenerateRandomPassword(length int) (string, error)
• func SanitizeInputMiddleware(next http.Handler) http.Handler
• func SecurityHeaders(next http.Handler) http.Handler
• type AdminAuditLogger
  • func NewAdminAuditLogger() *AdminAuditLogger
  • func (a *AdminAuditLogger) Middleware(next http.Handler) http.Handler
• type ApprovedUsersProvider
• type Config
• type ControlPlaneAuthorizer
• type DMUsersProvider
• type DetectedSpam
• type DetectedSpamProvider
• type Detector
• type Dictionary
• type DictionaryProvider
• type Locator
• type MetricsProvider
• type OnboardRequest
• type OnboardResult
• type OnboardingService
• type RestoreService
• type RuleSetProvider
• type Server
  • func NewServer(config Config) *Server
  • func (s *Server) Run(ctx context.Context) error
• type Settings
• type SpamFilter
• type StorageEngine
• type TenantRateLimiter
  • func NewTenantRateLimiter(r rate.Limit, burst int) *TenantRateLimiter
  • func (rl *TenantRateLimiter) Middleware(next http.Handler) http.Handler
• type TenantStatusMiddleware
  • func (m *TenantStatusMiddleware) Handler(next http.Handler) http.Handler
• type TenantStatusProvider

Functions

func CSRFTokenMiddleware

func CSRFTokenMiddleware(next http.Handler) http.Handler

func GenerateRandomPassword

func GenerateRandomPassword(length int) (string, error)

GenerateRandomPassword generates a random password of a given length

func SanitizeInputMiddleware

func SanitizeInputMiddleware(next http.Handler) http.Handler

func SecurityHeaders

func SecurityHeaders(next http.Handler) http.Handler

Types

type AdminAuditLogger

type AdminAuditLogger struct{}

func NewAdminAuditLogger

func NewAdminAuditLogger() *AdminAuditLogger

func (*AdminAuditLogger) Middleware

func (a *AdminAuditLogger) Middleware(next http.Handler) http.Handler

type ApprovedUsersProvider

type ApprovedUsersProvider interface {
	List(ctx context.Context, tenantID string) ([]approved.UserInfo, error)
	Add(ctx context.Context, tenantID string, user approved.UserInfo) error
	Remove(ctx context.Context, tenantID string, id string) error
}

ApprovedUsersProvider provides access to approved users through the control plane service layer.

type Config

type Config struct {
	Version               string                     // version to show in /ping
	ListenAddr            string                     // listen address
	Detector              Detector                   // spam detector
	SpamFilter            SpamFilter                 // spam filter (bot)
	DetectedSpamStore     DetectedSpam               // detected spam storage (fallback when DetectedSpamProvider is nil)
	DetectedSpamProvider  DetectedSpamProvider       // control plane detected spam service
	Locator               Locator                    // locator for user info
	DictionaryStore       Dictionary                 // dictionary storage (fallback when DictionaryProvider is nil)
	DictionaryProvider    DictionaryProvider         // control plane dictionary service (takes precedence over DictionaryStore)
	StorageEngine         StorageEngine              // database engine access for backups
	DMUsersProvider       DMUsersProvider            // provider for recent DM users
	RuleSetProvider       RuleSetProvider            // control plane rule set service
	ControlPlaneAuth      ControlPlaneAuthorizer     // role authorizer for control plane endpoints
	ApprovedUsersProvider ApprovedUsersProvider      // control plane approved users service
	TenantStatusProvider  TenantStatusProvider       // checks if tenant is active (nil = skip check)
	RateLimiter           *TenantRateLimiter         // per-tenant rate limiter (nil = unlimited)
	AuthPasswd            string                     // basic auth password for user "tg-spam"
	AuthHash              string                     // basic auth bcrypt hash for user "tg-spam", takes precedence over AuthPasswd
	AuditService          *audit.Service             // audit service for incidents
	AppealService         *audit.AppealService       // appeal service for incident appeals
	FeedbackService       *feedback.Service          // feedback service for labeling
	ReviewService         *feedback.ReviewService    // review service for candidates
	KnowledgeService      *feedback.KnowledgeService // knowledge snapshot service
	OnboardingProvider    OnboardingService          // tenant onboarding/offboarding
	RestoreProvider       RestoreService             // tenant restore from backup
	MetricsCollector      MetricsProvider            // SLO/SLA metrics
	Dbg                   bool                       // debug mode
	Settings              Settings                   // application settings
	// EnvPinnedKeys lists RuleSet JSON paths whose value is pinned by an env var
	// and will override the stored ruleset on the next restart.
	EnvPinnedKeys map[string]bool
}

Config defines server parameters

type ControlPlaneAuthorizer

type ControlPlaneAuthorizer interface {
	Authorize(ctx context.Context, workspaceID string, userID string, access string) error
}

ControlPlaneAuthorizer checks workspace role permissions for control plane endpoints.

type DMUsersProvider

type DMUsersProvider interface {
	GetDMUsers() []events.DMUser
}

DMUsersProvider provides access to recent DM users for the admin UI

type DetectedSpam

type DetectedSpam interface {
	Read(ctx context.Context, tenantID string) ([]storage.DetectedSpamInfo, error)
	SetAddedToSamplesFlag(ctx context.Context, tenantID string, id int64) error
	FindByUserID(ctx context.Context, tenantID string, userID int64) (*storage.DetectedSpamInfo, error)
}

DetectedSpam is a storage interface used to get detected spam messages and set added flag.

type DetectedSpamProvider

type DetectedSpamProvider interface {
	DetectedSpam
}

DetectedSpamProvider provides access to detected spam through the control plane service layer.

type Detector

type Detector interface {
	Check(req spamcheck.Request) (spam bool, cr []spamcheck.Response)
	ApprovedUsers() []approved.UserInfo
	AddApprovedUser(user approved.UserInfo) error
	RemoveApprovedUser(id string) error
	GetLuaPluginNames() []string // Returns the list of available Lua plugin names
}

Detector is a spam detector interface.

type Dictionary

type Dictionary interface {
	Add(ctx context.Context, tenantID string, t storage.DictionaryType, data string) error
	Delete(ctx context.Context, tenantID string, id int64) error
	Read(ctx context.Context, tenantID string, t storage.DictionaryType) ([]string, error)
	ReadWithIDs(ctx context.Context, tenantID string, t storage.DictionaryType) ([]storage.DictionaryEntry, error)
	Stats(ctx context.Context, tenantID string) (*storage.DictionaryStats, error)
}

Dictionary is a storage interface for managing stop phrases and ignored words

type DictionaryProvider

type DictionaryProvider interface {
	Dictionary
}

DictionaryProvider provides access to dictionary management through the control plane service layer.

type Locator

type Locator interface {
	UserIDByName(ctx context.Context, userName string) int64
	UserNameByID(ctx context.Context, userID int64) string
}

Locator is a storage interface used to get user id by name and vice versa.

type MetricsProvider

type MetricsProvider interface {
	Inc(name string)
	Add(name string, delta int64)
	Observe(name string, duration time.Duration)
	Snapshot() any
}

type OnboardRequest

type OnboardRequest struct {
	TenantID string `json:"tenant_id"`
	Name     string `json:"name"`
	OwnerID  string `json:"owner_id"`
	GID      string `json:"gid"`
}

type OnboardResult

type OnboardResult struct {
	TenantID    string `json:"tenant_id"`
	WorkspaceID string `json:"workspace_id"`
	RuleSetVer  int    `json:"rule_set_version"`
}

type OnboardingService

type OnboardingService interface {
	Onboard(ctx context.Context, req OnboardRequest) (*OnboardResult, error)
	Offboard(ctx context.Context, tenantID string) error
}

type RestoreService

type RestoreService interface {
	RestoreTenant(ctx context.Context, tenantID string, r io.Reader) error
}

type RuleSetProvider

type RuleSetProvider interface {
	Get(ctx context.Context, workspaceID string) (rules.RuleSet, error)
	Update(ctx context.Context, workspaceID string, source string, rs rules.RuleSet) (rules.RuleSet, error)
}

RuleSetProvider provides access to the active rule set and allows runtime updates.

type Server

type Server struct {
	Config
}

Server is a web API server.

func NewServer

func NewServer(config Config) *Server

NewServer creates a new web API server.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts server and accepts requests checking for spam messages.

type Settings

type Settings struct {
	TenantID                 string        `json:"tenant_id"`
	BotUsername              string        `json:"bot_username"`
	PrimaryGroup             string        `json:"primary_group"`
	AdminGroup               string        `json:"admin_group"`
	DisableAdminSpamForward  bool          `json:"disable_admin_spam_forward"`
	LoggerEnabled            bool          `json:"logger_enabled"`
	SuperUsers               []string      `json:"super_users"`
	NoSpamReply              bool          `json:"no_spam_reply"`
	CasEnabled               bool          `json:"cas_enabled"`
	MetaEnabled              bool          `json:"meta_enabled"`
	MetaLinksLimit           int           `json:"meta_links_limit"`
	MetaMentionsLimit        int           `json:"meta_mentions_limit"`
	MetaLinksOnly            bool          `json:"meta_links_only"`
	MetaImageOnly            bool          `json:"meta_image_only"`
	MetaVideoOnly            bool          `json:"meta_video_only"`
	MetaAudioOnly            bool          `json:"meta_audio_only"`
	MetaForwarded            bool          `json:"meta_forwarded"`
	MetaKeyboard             bool          `json:"meta_keyboard"`
	MetaContactOnly          bool          `json:"meta_contact_only"`
	MetaUsernameSymbols      string        `json:"meta_username_symbols"`
	MetaGiveaway             bool          `json:"meta_giveaway"`
	MultiLangLimit           int           `json:"multi_lang_limit"`
	LLMConsensus             string        `json:"llm_consensus"`
	LLMHistoryContextSize    int           `json:"llm_history_context_size"`
	OpenAIEnabled            bool          `json:"openai_enabled"`
	OpenAIVeto               bool          `json:"openai_veto"`
	OpenAIHistorySize        int           `json:"openai_history_size"`
	OpenAIModel              string        `json:"openai_model"`
	OpenAICheckShortMessages bool          `json:"openai_check_short_messages"`
	OpenAICustomPrompts      []string      `json:"openai_custom_prompts"`
	GeminiEnabled            bool          `json:"gemini_enabled"`
	GeminiVeto               bool          `json:"gemini_veto"`
	GeminiHistorySize        int           `json:"gemini_history_size"`
	GeminiModel              string        `json:"gemini_model"`
	GeminiCheckShortMessages bool          `json:"gemini_check_short_messages"`
	GeminiCustomPrompts      []string      `json:"gemini_custom_prompts"`
	LuaPluginsEnabled        bool          `json:"lua_plugins_enabled"`
	LuaPluginsDir            string        `json:"lua_plugins_dir"`
	LuaEnabledPlugins        []string      `json:"lua_enabled_plugins"`
	LuaDynamicReload         bool          `json:"lua_dynamic_reload"`
	LuaAvailablePlugins      []string      `json:"lua_available_plugins"` // the list of all available Lua plugins
	SamplesDataPath          string        `json:"samples_data_path"`
	DynamicDataPath          string        `json:"dynamic_data_path"`
	WatchIntervalSecs        int           `json:"watch_interval_secs"`
	SimilarityThreshold      float64       `json:"similarity_threshold"`
	MinMsgLen                int           `json:"min_msg_len"`
	MaxEmoji                 int           `json:"max_emoji"`
	MinSpamProbability       float64       `json:"min_spam_probability"`
	ParanoidMode             bool          `json:"paranoid_mode"`
	FirstMessagesCount       int           `json:"first_messages_count"`
	StartupMessageEnabled    bool          `json:"startup_message_enabled"`
	TrainingEnabled          bool          `json:"training_enabled"`
	StorageTimeout           time.Duration `json:"storage_timeout"`
	SoftBanEnabled           bool          `json:"soft_ban_enabled"`
	AbnormalSpacingEnabled   bool          `json:"abnormal_spacing_enabled"`
	HistorySize              int           `json:"history_size"`
	DebugModeEnabled         bool          `json:"debug_mode_enabled"`
	DryModeEnabled           bool          `json:"dry_mode_enabled"`
	TGDebugModeEnabled       bool          `json:"tg_debug_mode_enabled"`
}

Settings contains all application settings

type SpamFilter

type SpamFilter interface {
	UpdateSpam(msg string) error
	UpdateHam(msg string) error
	ReloadSamples(ctx context.Context) (err error)
	DynamicSamples(ctx context.Context) (spam, ham []string, err error)
	RemoveDynamicSpamSample(sample string) error
	RemoveDynamicHamSample(sample string) error
}

SpamFilter is a spam filter, bot interface.

type StorageEngine

type StorageEngine interface {
	Backup(ctx context.Context, w io.Writer) error
	Type() engine.Type
	BackupSqliteAsPostgres(ctx context.Context, w io.Writer) error
}

StorageEngine provides access to the database engine for operations like backup

type TenantRateLimiter

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

func NewTenantRateLimiter

func NewTenantRateLimiter(r rate.Limit, burst int) *TenantRateLimiter

func (*TenantRateLimiter) Middleware

func (rl *TenantRateLimiter) Middleware(next http.Handler) http.Handler

type TenantStatusMiddleware

type TenantStatusMiddleware struct {
	Checker  TenantStatusProvider
	TenantID string
}

func (*TenantStatusMiddleware) Handler

func (m *TenantStatusMiddleware) Handler(next http.Handler) http.Handler

type TenantStatusProvider

type TenantStatusProvider interface {
	Status(ctx context.Context, tenantID string) (string, error)
}