octanox

package module
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2025 License: MIT Imports: 24 Imported by: 0

README

octanox

Octanox is a fullstack web API framework leveraging the Gin framework.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Error 

func Error(err error) error

Error wraps the given error and adds a stack trace to it.

Types

type ApiKeyAuthenticator 

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

func (*ApiKeyAuthenticator) Authenticate 

func (a *ApiKeyAuthenticator) Authenticate(c *gin.Context) (User, error)

func (*ApiKeyAuthenticator) Method 

func (a *ApiKeyAuthenticator) Method() AuthenticationMethod

type AuthenticationMethod 

type AuthenticationMethod int

AuthenticationMethod is an enum that defines the authentication methods. 

const (
	// AuthenticationMethodBearer is the Bearer authentication method.
	AuthenticationMethodBearer AuthenticationMethod = iota
	// AuthenticationMethodBasic is the Basic authentication method.
	AuthenticationMethodBasic
	// AuthenticationMethodApiKey is the API key authentication method.
	AuthenticationMethodApiKey
	// AuthenticationMethodBearerOAuth2 is the Bearer OAuth2 authentication method.
	AuthenticationMethodBearerOAuth2
)

type Authenticator 

type Authenticator interface {
	// Method returns the authentication method.
	Method() AuthenticationMethod

	// Authenticate authenticates the client request. Gets the client request context and returns the authenticated user.
	// If the authentication fails, it should return nil.
	Authenticate(c *gin.Context) (User, error)
}

Authenticator is an struct that defines the authentication module.

type AuthenticatorBuilder 

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

AuthenticatorBuilder is a struct that helps build the Authenticator.

func (*AuthenticatorBuilder) ApiKey 

func (b *AuthenticatorBuilder) ApiKey() *ApiKeyAuthenticator

ApiKey creates a new ApiKeyAuthenticator and plugs it into the Authenticator.

func (*AuthenticatorBuilder) Basic 

func (b *AuthenticatorBuilder) Basic() *BasicAuthenticator

Basic creates a new BasicAuthenticator and plugs it into the Authenticator.

func (*AuthenticatorBuilder) Bearer 

func (b *AuthenticatorBuilder) Bearer(secret, basePath string) *BearerAuthenticator

Bearer creates a new BearerAuthenticator with the given secret and plugs it into the Authenticator. The basePath is the base path for the authentication routes. The secret is the secret key used to sign the JWT token. Defaults to 1 day for the token expiration time.

func (*AuthenticatorBuilder) BearerOAuth2 

func (b *AuthenticatorBuilder) BearerOAuth2(oauth2Endpoint oauth2.Endpoint, scopes []string, clientId, clientSecret, domain, loginSuccessRedirect, secret, basePath string) *OAuth2BearerAuthenticator

BearerOAuth2 creates a new OAuth2BearerAuthenticator with the given OAuth2 parameters and plugs it into the Authenticator. The basePath is the base path for the authentication routes. The clientId is the OAuth2 client ID. The clientSecret is the OAuth2 client secret. The oauth2Endpoint is the OAuth2 endpoint. The scopes is the list of scopes to request. The domain is the domain of this application. The domain must not have a trailing slash. The domain should contain any prefix The loginSuccessRedirect is the URL to redirect to after a successful login. The secret is the secret key used to sign the JWT token.

type BasicAuthenticator 

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

func (*BasicAuthenticator) Authenticate 

func (a *BasicAuthenticator) Authenticate(c *gin.Context) (User, error)

func (*BasicAuthenticator) Method 

func (a *BasicAuthenticator) Method() AuthenticationMethod

type BearerAuthenticator 

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

func (*BearerAuthenticator) Authenticate 

func (a *BearerAuthenticator) Authenticate(c *gin.Context) (User, error)

func (*BearerAuthenticator) Method 

func (a *BearerAuthenticator) Method() AuthenticationMethod

func (*BearerAuthenticator) SetExp 

func (a *BearerAuthenticator) SetExp(exp int64)

SetExp sets the expiration time for the token.

type Context 

type Context map[string]interface{}

Context is a type that represents a generic context.

func FromMap 

func FromMap(m map[string]interface{}) Context

FromMap is a function that converts a map to a Context.

func FromQuery 

func FromQuery(c *gin.Context) Context

FromQuery is a function that converts a Gin context (query parameters) to a Context.

func (Context) Get 

func (c Context) Get(key string) (interface{}, bool)

Get is a function that gets a value from a Context.

func (Context) GetBool 

func (c Context) GetBool(key string) (bool, bool)

GetBool is a function that gets a bool value from a Context.

func (Context) GetFloat 

func (c Context) GetFloat(key string) (float64, bool)

GetFloat is a function that gets a float64 value from a Context.

func (Context) GetInt 

func (c Context) GetInt(key string) (int, bool)

GetInt is a function that gets an int value from a Context.

func (Context) GetString 

func (c Context) GetString(key string) (string, bool)

GetString is a function that gets a string value from a Context.

func (Context) GetStringSlice 

func (c Context) GetStringSlice(key string) ([]string, bool)

GetStringSlice is a function that gets a string slice value from a Context.

func (Context) Has 

func (c Context) Has(key string) bool

Has is a function that checks if a Context has a key.

func (Context) Set 

func (c Context) Set(key string, value interface{}) Context

Set is a function that sets a key-value pair to a Context.

type DeleteRequest 

type DeleteRequest struct {
	Request
}

DeleteRequest is a struct that represents a DELETE request.

type GetRequest 

type GetRequest struct {
	Request
}

GetRequest is a struct that represents a GET request.

type HeadRequest 

type HeadRequest struct {
	Request
}

HeadRequest is a struct that represents a HEAD request.

type Hook 

type Hook string

Hook is the type of a hook function that can be registered within the Octanox framework. 

const (
	// Init is a hook that is called when the Octanox runtime is initializing.
	Hook_Init Hook = "init"
	// BeforeStart is a hook that is called when the Octanox runtime is registering its routes just before starting the web server. Here all routes should be registered. Before dry-run checks.
	Hook_BeforeStart Hook = "before_start"
	// Start is a hook that is called when the Octanox runtime is starting. After dry-run checks and before the web server starts.
	Hook_Start Hook = "start"
	// Shutdown is a hook that is called when the Octanox runtime is shutting down.
	Hook_Shutdown Hook = "shutdown"
)

type Instance 

type Instance struct {
	*SubRouter
	// Gin is the underlying Gin engine that powers the Octanox framework's web server.
	Gin *gin.Engine
	// Authenticator is the underlying authenticator that powers the Octanox framework's authentication operations. Can be nil if no authenticator has been created.
	Authenticator Authenticator
	// contains filtered or unexported fields
}

Instance is a struct that represents an instance of the Octanox framework. 

var Current *Instance

Current is the current instance of the Octanox framework. Can be nil if no instance has been created.

func New 

func New() *Instance

New creates a new instance of the Octanox framework. If an instance already exists, it will return the existing instance. This won't start the Octanox runtime, you need to call Run() on the instance to start the runtime.

func (*Instance) Authenticate 

func (i *Instance) Authenticate(provider interface{}) *AuthenticatorBuilder

Plugs in the authentication module into Octanox.

func (*Instance) ErrorHandler 

func (i *Instance) ErrorHandler(f func(error))

ErrorHandler registers an error handler function to be called when an error occurs in the Octanox runtime.

func (*Instance) Hook 

func (i *Instance) Hook(hook Hook, f func(*Instance))

Hook registers a hook function to be called at a specific point in the Octanox runtime.

func (*Instance) RegisterSerializer 

func (i *Instance) RegisterSerializer(obj interface{}, serializer interface{}) *Instance

RegisterSerializer is a function that registers a serializer for a given type.

func (*Instance) Run 

func (i *Instance) Run()

Run starts the Octanox runtime. This function will block the current goroutine. If any error occurs, it will panic.

func (*Instance) Serialize 

func (i *Instance) Serialize(obj interface{}, c Context) any

Serialize serializes an object into another form using the registered serializers.

type OAuth2BearerAuthenticator 

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

func (*OAuth2BearerAuthenticator) Authenticate 

func (a *OAuth2BearerAuthenticator) Authenticate(c *gin.Context) (User, error)

func (*OAuth2BearerAuthenticator) EnableOIDCValidation added in v0.1.2 

func (a *OAuth2BearerAuthenticator) EnableOIDCValidation(issuer string)

EnableOIDCValidation enforces validation of ID token against the given issuer using JWKS.

func (*OAuth2BearerAuthenticator) Method 

func (a *OAuth2BearerAuthenticator) Method() AuthenticationMethod

func (*OAuth2BearerAuthenticator) SetExp 

func (a *OAuth2BearerAuthenticator) SetExp(exp int64)

SetExp sets the expiration time for the token.

type OAuth2UserProvider 

type OAuth2UserProvider interface {
	// ProvideForLogin provides the user data for the given OAuth2 access token. If the user data cannot be provided, it should return an error.
	ProvideForLogin(oauth2AccessToken string) (User, error)
	// ProvideByID provides the user data for the given user ID. If the user data cannot be provided, it should return an error.
	ProvideByID(id uuid.UUID) (User, error)
}

OAuth2UserProvider is an interface that allows the authentication module to access the user data from OAuth2 providers.

type OptionsRequest 

type OptionsRequest struct {
	Request
}

OptionsRequest is a struct that represents an OPTIONS request.

type PatchRequest 

type PatchRequest struct {
	Request
}

PatchRequest is a struct that represents a PATCH request.

type PostRequest 

type PostRequest struct {
	Request
}

PostRequest is a struct that represents a POST request.

type PutRequest 

type PutRequest struct {
	Request
}

PutRequest is a struct that represents a PUT request.

type Request 

type Request struct{}

func (Request) Failed 

func (r Request) Failed(status int, message string)

Failed is a function that can be called to indicate that the request has failed and should abort with a specific status code and message. This function will panic with a failedRequest struct that will be caught by the Octanox framework.

type Serializer 

type Serializer func(interface{}, Context) any

Serializer is a type that represents a serializer function.

type StateMap 

type StateMap map[string]bool

func (StateMap) Generate 

func (s StateMap) Generate(seconds int) string

func (StateMap) Validate 

func (s StateMap) Validate(state string) bool

func (StateMap) ValidateOnce 

func (s StateMap) ValidateOnce(state string) bool

type StringStateMap added in v0.1.2 

type StringStateMap map[string]string

StringStateMap stores string values by key with expiry similar to StateMap.

func (StringStateMap) Pop added in v0.1.2 

func (s StringStateMap) Pop(key string) string

func (StringStateMap) Store added in v0.1.2 

func (s StringStateMap) Store(key, value string, seconds int)

type SubRouter 

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

Router is a struct that represents a router in the Octanox framework. It wraps around a Gin router group with the only two differences to populate the request handlers, handling responses and emit the DTOs to the client code generation process.

func (*SubRouter) Register 

func (r *SubRouter) Register(path string, handler interface{}, roles ...string)

Register registers a new route handler. The function automatically detects the method, request and response type. If any of these detection fails, it will panic. If an authenticator is set, the route will be protected. Should return the response. Can return a Context to set the serializer context.

func (*SubRouter) RegisterManually 

func (r *SubRouter) RegisterManually(path string, handler interface{}, authenticated bool, roles ...string)

RegisterManually registers a new route handler. The function automatically detects the method, request and response type. If any of these detection fails, it will panic.

func (*SubRouter) RegisterProtected 

func (r *SubRouter) RegisterProtected(path string, handler interface{}, roles ...string)

RegisterProtected registers a new protected route handler. The function automatically detects the method, request and response type. If any of these detection fails, it will panic.

func (*SubRouter) RegisterPublic 

func (r *SubRouter) RegisterPublic(path string, handler interface{}, roles ...string)

RegisterPublic registers a new public route handler. The function automatically detects the method, request and response type. If any of these detection fails, it will panic.

func (*SubRouter) Router 

func (r *SubRouter) Router(url string) *SubRouter

Router creates a new router with the given URL prefix.

type TraceRequest 

type TraceRequest struct {
	Request
}

TraceRequest is a struct that represents a TRACE request.

type User 

type User interface {
	// ID returns the user's ID.
	ID() uuid.UUID
	// HasRole checks if the user has the given role.
	HasRole(role string) bool
}

User is an interface that defines the authenticated user model.

type UserProvider 

type UserProvider interface {
	// ProvideByUserPass provides the user data for the given username and password. If the user data cannot be provided, it should return an error.
	ProvideByUserPass(username, password string) (User, error)
	// ProvideByID provides the user data for the given user ID. If the user data cannot be provided, it should return an error.
	// This should be used to provide the user data when the authentication is called, like providing it by the user ID in the token.
	ProvideByID(id uuid.UUID) (User, error)
	// ProvideByApiKey provides the user data for the given API key. If the user data cannot be provided, it should return an error.
	ProvideByApiKey(apiKey string) (User, error)
}

UserProvider is an interface that allows the authentication module to access the user data.

Source Files

View all Source files

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.