server

type Auth interface {
	// Authenticate attempts to identify and return the user associated with
	// an incoming HTTP request, typically by inspecting headers or tokens.
	Authenticate(*http.Request) (*authschema.User, error)

	// Authorize checks if a given user has the necessary permissions (scopes)
	// to perform an action.
	Authorize(context.Context, *authschema.User, ...string) error
}

type Cmd interface {
	// Run the command
	Run() error

	// Return the context
	Context() context.Context

	// Return the debug mode
	GetDebug() DebugLevel

	// Return the endpoint
	GetEndpoint(paths ...string) (*url.URL, error)

	// Return the HTTP client options
	GetClientOpts() []client.ClientOpt
}

type DebugLevel uint

type HTTPMiddleware interface {
	// Return a http handler with middleware as the parent handler
	HandleFunc(http.HandlerFunc) http.HandlerFunc
}

type HTTPRouter interface {
	// Return the CORS origin
	Origin() string

	// Register a function to handle a URL path
	HandleFunc(context.Context, string, http.HandlerFunc)

	// Register serving of static files from a filesystem
	HandleFS(context.Context, string, fs.FS)
}

type LDAP interface {
	// Introspection
	ListObjectClasses(context.Context) ([]*ldapschema.ObjectClass, error)    // Return all classes
	ListAttributeTypes(context.Context) ([]*ldapschema.AttributeType, error) // Return all attributes

	// Objects
	List(context.Context, ldapschema.ObjectListRequest) (*ldapschema.ObjectList, error) // List all objects in the directory
	Get(context.Context, string) (*ldapschema.Object, error)                            // Get an object
	Create(context.Context, string, url.Values) (*ldapschema.Object, error)             // Create a new object with attributes
	Update(context.Context, string, url.Values) (*ldapschema.Object, error)             // Update an object with attributes
	Delete(context.Context, string) (*ldapschema.Object, error)                         // Delete an object

	// Users
	ListUsers(context.Context, ldapschema.ObjectListRequest) (*ldapschema.ObjectList, error) // List users
	GetUser(context.Context, string) (*ldapschema.Object, error)                             // Get a user
	CreateUser(context.Context, string, url.Values) (*ldapschema.Object, error)              // Create a user with attributes
	DeleteUser(context.Context, string) (*ldapschema.Object, error)                          // Delete a user

	// Groups
	ListGroups(context.Context, ldapschema.ObjectListRequest) (*ldapschema.ObjectList, error) // List groups
	GetGroup(context.Context, string) (*ldapschema.Object, error)                             // Get a group
	CreateGroup(context.Context, string, url.Values) (*ldapschema.Object, error)              // Create a group with attributes
	DeleteGroup(context.Context, string) (*ldapschema.Object, error)                          // Delete a group

	// Auth
	Bind(context.Context, string, string) (*ldapschema.Object, error)                    // Check credentials
	ChangePassword(context.Context, string, string, *string) (*ldapschema.Object, error) // Change password for a user, and return the user object
}

type Logger interface {
	HTTPMiddleware

	// Debug logs a debugging message.
	Debug(context.Context, ...any)

	// Debugf logs a formatted debugging message.
	Debugf(context.Context, string, ...any)

	// Print logs an informational message.
	Print(context.Context, ...any)

	// Printf logs a formatted informational message.
	Printf(context.Context, string, ...any)

	// With returns a new Logger that includes the given key-value pairs
	// in its structured log output.
	With(...any) Logger
}

type PG interface {
	// Conn returns the underlying connection pool object.
	Conn() pg.PoolConn
}

type PGCallback func(context.Context, any) error

type PGQueue interface {
	PG

	// Namespace returns the namespace of the queue.
	Namespace() string

	// RegisterTicker registers a periodic task (ticker) with a callback function.
	// It returns the metadata of the registered ticker.
	RegisterTicker(context.Context, pgschema.TickerMeta, PGCallback) (*pgschema.Ticker, error)

	// RegisterQueue registers a task queue with a callback function.
	// It returns the metadata of the registered queue.
	RegisterQueue(context.Context, pgschema.QueueMeta, PGCallback) (*pgschema.Queue, error)

	// CreateTask adds a new task to a specified queue with a payload and optional delay.
	// It returns the metadata of the created task.
	CreateTask(context.Context, string, any, time.Duration) (*pgschema.Task, error)

	// UnmarshalPayload unmarshals a payload into a destination object.
	UnmarshalPayload(dest any, payload any) error
}

type Plugin interface {
	// Return the unique name for the plugin
	Name() string

	// Return a description of the plugin
	Description() string

	// Create a task from a plugin
	New(context.Context) (Task, error)
}

type PluginResolverFunc func(context.Context, string, Plugin) error

type Provider interface {
	Task

	// Write out the plugin configuration to a writer
	WriteConfig(io.Writer) error

	// Return the plugins registered with the provider
	Plugins() []Plugin

	// Load a plugin by name and label, and provide a resolver function
	Load(string, string, PluginResolverFunc) error

	// Return a task given a plugin label
	Task(context.Context, string) Task
}

type Task interface {
	// Run a task
	Run(context.Context) error
}