gitcaddy-server/modules/plugins/plugin.go

// Copyright 2026 MarketAlly. All rights reserved.
// SPDX-License-Identifier: MIT

package plugins

import (
	"context"

	"xorm.io/xorm"
)

// Plugin defines the interface that all GitCaddy plugins must implement
type Plugin interface {
	// Name returns the unique identifier for this plugin
	Name() string

	// Version returns the plugin version
	Version() string

	// Description returns a human-readable description
	Description() string

	// Init is called when the plugin is loaded
	Init(ctx context.Context) error

	// Shutdown is called when the server is shutting down
	Shutdown(ctx context.Context) error
}

// DatabasePlugin is implemented by plugins that need database tables
type DatabasePlugin interface {
	Plugin

	// RegisterModels returns the models to be registered with the database
	RegisterModels() []any

	// Migrate runs any database migrations for this plugin
	Migrate(ctx context.Context, x *xorm.Engine) error
}

// WebRoutesPlugin is implemented by plugins that add web UI routes
type WebRoutesPlugin interface {
	Plugin

	// RegisterWebRoutes adds routes to the web UI router
	// The router is a *web.Router from the gitcaddy server
	RegisterWebRoutes(m any)
}

// APIRoutesPlugin is implemented by plugins that add API routes
type APIRoutesPlugin interface {
	Plugin

	// RegisterAPIRoutes adds routes to the API router
	// The router is a *web.Router from the gitcaddy server
	RegisterAPIRoutes(m any)
}

// RepoRoutesPlugin is implemented by plugins that add per-repository routes
type RepoRoutesPlugin interface {
	Plugin

	// RegisterRepoWebRoutes adds routes under /{owner}/{repo}/
	// The router is a *web.Router from the gitcaddy server
	RegisterRepoWebRoutes(m any)

	// RegisterRepoAPIRoutes adds routes under /api/v1/repos/{owner}/{repo}/
	// The router is a *web.Router from the gitcaddy server
	RegisterRepoAPIRoutes(m any)
}

// LicensedPlugin is implemented by plugins that require a license
type LicensedPlugin interface {
	Plugin

	// ValidateLicense checks if the plugin is properly licensed
	ValidateLicense(ctx context.Context) error

	// LicenseInfo returns information about the current license
	LicenseInfo() *LicenseInfo
}

// LicenseInfo contains license details
type LicenseInfo struct {
	Valid       bool
	Tier        string // e.g., "solo", "pro", "team", "enterprise"
	CustomerID  string
	ExpiresAt   int64
	GracePeriod bool // true if in grace period after expiry
}