api package - forge.lthn.ai/core/api - Go Packages
Documentation ¶ Overview ¶ Package api provides a Gin-based REST framework with OpenAPI generation. Subsystems implement RouteGroup to register their own endpoints. Index ¶ Constants func ExportSpec(w io.Writer, format string, builder *SpecBuilder, groups []RouteGroup) error func ExportSpecToFile(path, format string, builder *SpecBuilder, groups []RouteGroup) error func GetLocale(c *gin.Context) string func GetMessage(c *gin.Context, key string) (string, bool) func NewTracerProvider(exporter sdktrace.SpanExporter) *sdktrace.TracerProvider func RequireAuth() gin.HandlerFunc func RequireGroup(group string) gin.HandlerFunc func SupportedLanguages() []string func SupportedLanguagesIter() iter.Seq[string] type AuthentikConfig type AuthentikUser func GetUser(c *gin.Context) *AuthentikUser func (u *AuthentikUser) HasGroup(group string) bool type DescribableGroup type Engine func New(opts ...Option) (*Engine, error) func (e *Engine) Addr() string func (e *Engine) Channels() []string func (e *Engine) ChannelsIter() iter.Seq[string] func (e *Engine) Groups() []RouteGroup func (e *Engine) GroupsIter() iter.Seq[RouteGroup] func (e *Engine) Handler() http.Handler func (e *Engine) Register(group RouteGroup) func (e *Engine) Serve(ctx context.Context) error type Error type GraphQLOption func WithGraphQLPath(path string) GraphQLOption func WithPlayground() GraphQLOption type I18nConfig type Meta type Option func WithAddr(addr string) Option func WithAuthentik(cfg AuthentikConfig) Option func WithAuthz(enforcer *casbin.Enforcer) Option func WithBearerAuth(token string) Option func WithBrotli(level ...int) Option func WithCORS(allowOrigins ...string) Option func WithCache(ttl time.Duration) Option func WithExpvar() Option func WithGraphQL(schema graphql.ExecutableSchema, opts ...GraphQLOption) Option func WithGzip(level ...int) Option func WithHTTPSign(secrets httpsign.Secrets, opts ...httpsign.Option) Option func WithI18n(cfg ...I18nConfig) Option func WithLocation() Option func WithMiddleware(mw ...gin.HandlerFunc) Option func WithPprof() Option func WithRequestID() Option func WithSSE(broker *SSEBroker) Option func WithSecure() Option func WithSessions(name string, secret []byte) Option func WithSlog(logger *slog.Logger) Option func WithStatic(urlPrefix, root string) Option func WithSwagger(title, description, version string) Option func WithTimeout(d time.Duration) Option func WithTracing(serviceName string, opts ...otelgin.Option) Option func WithWSHandler(h http.Handler) Option type Response func Fail(code, message string) Response[any] func FailWithDetails(code, message string, details any) Response[any] func OK[T any](data T) Response[T] func Paginated[T any](data T, page, perPage, total int) Response[T] type RouteDescription type RouteGroup type SDKGenerator func (g *SDKGenerator) Available() bool func (g *SDKGenerator) Generate(ctx context.Context, language string) error type SSEBroker func NewSSEBroker() *SSEBroker func (b *SSEBroker) ClientCount() int func (b *SSEBroker) Drain() func (b *SSEBroker) Handler() gin.HandlerFunc func (b *SSEBroker) Publish(channel, event string, data any) type SpecBuilder func (sb *SpecBuilder) Build(groups []RouteGroup) ([]byte, error) type StreamGroup type ToolBridge func NewToolBridge(basePath string) *ToolBridge func (b *ToolBridge) Add(desc ToolDescriptor, handler gin.HandlerFunc) func (b *ToolBridge) BasePath() string func (b *ToolBridge) Describe() []RouteDescription func (b *ToolBridge) DescribeIter() iter.Seq[RouteDescription] func (b *ToolBridge) Name() string func (b *ToolBridge) RegisterRoutes(rg *gin.RouterGroup) func (b *ToolBridge) Tools() []ToolDescriptor func (b *ToolBridge) ToolsIter() iter.Seq[ToolDescriptor] type ToolDescriptor Constants ¶ View Source const ( // BrotliBestSpeed is the lowest (fastest) Brotli compression level.
BrotliBestSpeed = brotli . BestSpeed // BrotliBestCompression is the highest (smallest output) Brotli level. BrotliBestCompression = brotli . BestCompression // BrotliDefaultCompression is the default Brotli compression level. BrotliDefaultCompression = brotli . DefaultCompression ) Variables ¶ This section is empty. Functions ¶ func ExportSpec ¶ func ExportSpec(w io . Writer , format string , builder * SpecBuilder , groups [] RouteGroup ) error ExportSpec generates the OpenAPI spec and writes it to w.
Format must be "json" or "yaml". func ExportSpecToFile ¶ func ExportSpecToFile(path, format string , builder * SpecBuilder , groups [] RouteGroup ) error ExportSpecToFile writes the spec to the given path. The parent directory is created if it does not exist. func GetLocale ¶ func GetLocale(c * gin . Context ) string GetLocale returns the detected locale for the current request. Returns "en" if the i18n middleware was not applied. func GetMessage ¶ func GetMessage(c * gin .
Context , key string ) ( string , bool ) GetMessage looks up a localised message by key for the current request. Returns the message string and true if found, or empty string and false if the key does not exist or the i18n middleware was not applied. func NewTracerProvider ¶ func NewTracerProvider(exporter sdktrace . SpanExporter ) * sdktrace . TracerProvider NewTracerProvider creates a TracerProvider configured with the given SpanExporter and returns it.
The caller is responsible for calling Shutdown on the returned provider when the application exits. This is a convenience helper for tests and simple deployments. Production setups should build their own TracerProvider with batching, resource attributes, and appropriate exporters. func RequireAuth ¶ func RequireAuth() gin . HandlerFunc RequireAuth is Gin middleware that rejects unauthenticated requests. It checks for a user set by the Authentik middleware and returns 401 when none is present. func RequireGroup ¶ func RequireGroup(group string ) gin .
HandlerFunc RequireGroup is Gin middleware that rejects requests from users who do not belong to the specified group. Returns 401 when no user is present and 403 when the user lacks the required group membership. func SupportedLanguages ¶ func SupportedLanguages() [] string SupportedLanguages returns the list of supported SDK target languages in sorted order for deterministic output. func SupportedLanguagesIter ¶ func SupportedLanguagesIter() iter .
Seq [ string ] SupportedLanguagesIter returns an iterator over supported SDK target languages in sorted order. Types ¶ type AuthentikConfig ¶ type AuthentikConfig struct { // Issuer is the OIDC issuer URL (e.g. https://auth.example.com/application/o/my-app/ ). Issuer string // ClientID is the OAuth2 client identifier. ClientID string // TrustedProxy enables reading X-authentik-* headers set by a reverse proxy. // When false, headers are ignored to prevent spoofing from untrusted sources.
TrustedProxy bool // PublicPaths lists additional paths that do not require authentication. // /health and /swagger are always public. PublicPaths [] string } AuthentikConfig holds settings for the Authentik forward-auth integration. type AuthentikUser ¶ type AuthentikUser struct { Username string `json:"username"` Email string `json:"email"` Name string `json:"name"` UID string `json:"uid"` Groups [] string `json:"groups,omitempty"` Entitlements [] string `json:"entitlements,omitempty"` JWT string `json:"-"` } AuthentikUser represents an authenticated user extracted from Authentik forward-auth headers or a validated JWT. func GetUser ¶ func GetUser(c * gin .
Context ) * AuthentikUser GetUser retrieves the AuthentikUser from the Gin context. Returns nil when no user has been set (unauthenticated request or middleware not active). func (*AuthentikUser) HasGroup ¶ func (u * AuthentikUser ) HasGroup(group string ) bool HasGroup reports whether the user belongs to the named group. type DescribableGroup ¶ type DescribableGroup interface { RouteGroup // Describe returns endpoint descriptions for OpenAPI generation.
Describe() [] RouteDescription } DescribableGroup extends Rou
The rest of this page is on the live site.