api

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: May 10, 2026 License: AGPL-3.0 Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Credential failures
	FailureReasonInvalidUsername   = "invalid_username"         // Username not found
	FailureReasonInvalidPassword   = "invalid_password"         // Wrong password
	FailureReasonPasswordChangeReq = "password_change_required" // Initial password not changed

	// Token failures
	FailureReasonTokenInvalid = "token_invalid" // Malformed or unknown token
	FailureReasonTokenExpired = "token_expired" // Token past expiration
	FailureReasonTokenRevoked = "token_revoked" // Token was revoked

	// Account status
	FailureReasonUserDisabled = "user_disabled" // Account disabled by admin
	FailureReasonUserDeleted  = "user_deleted"  // Account was deleted
)

REST API failure reasons

Variables

View Source 
var (
	ErrInvalidUID = errors.New("invalid UID")
)

API errors.

Functions

This section is empty.

Types

type ChangePasswordRequest 

type ChangePasswordRequest struct {
	Username        string `json:"username"`
	CurrentPassword string `json:"current_password" binding:"required"`
	NewPassword     string `json:"new_password" binding:"required"`
}

ChangePasswordRequest represents the request body for authenticated password change Requires re-authentication via username/password (not Bearer token) Username is optional when changing your own password (inferred from :uid param)

type CreateAPIKeyRequest 

type CreateAPIKeyRequest struct {
	Name      string     `json:"name" binding:"required"`
	ExpiresAt *time.Time `json:"expires_at"`
}

CreateAPIKeyRequest represents the request to create an API key

type CreateAPIKeyResponse 

type CreateAPIKeyResponse struct {
	ID        uuid.UUID  `json:"id"`
	Name      string     `json:"name"`
	Key       string     `json:"key"` // Only returned once!
	KeyPrefix string     `json:"key_prefix"`
	ExpiresAt *time.Time `json:"expires_at"`
	CreatedAt time.Time  `json:"created_at"`
}

CreateAPIKeyResponse represents the response when creating an API key

type CreateDatabaseRequest 

type CreateDatabaseRequest struct {
	Name              string `json:"name" binding:"required"`
	Description       string `json:"description"`
	Host              string `json:"host" binding:"required"`
	Port              int    `json:"port"`
	DatabaseName      string `json:"database_name"`
	Username          string `json:"username" binding:"required"`
	Password          string `json:"password" binding:"required"`
	SSLMode           string `json:"ssl_mode"`
	Protocol          string `json:"protocol"`
	OracleServiceName string `json:"oracle_service_name"`
}

CreateDatabaseRequest represents the request to create a database

type CreateGrantDefinitionRequest added in v0.10.0 

type CreateGrantDefinitionRequest struct {
	Name                string   `json:"name" binding:"required"`
	Description         string   `json:"description"`
	DurationSeconds     int64    `json:"duration_seconds" binding:"required"`
	Controls            []string `json:"controls"`
	MaxQueryCounts      *int64   `json:"max_query_counts"`
	MaxBytesTransferred *int64   `json:"max_bytes_transferred"`
}

CreateGrantDefinitionRequest is the JSON body for POST /grant-definitions.

type CreateGrantRequest 

type CreateGrantRequest struct {
	UserID              uuid.UUID `json:"user_id" binding:"required"`
	DatabaseID          uuid.UUID `json:"database_id" binding:"required"`
	Controls            []string  `json:"controls"` // Array of controls: read_only, block_copy, block_ddl
	StartsAt            time.Time `json:"starts_at" binding:"required"`
	ExpiresAt           time.Time `json:"expires_at" binding:"required"`
	MaxQueryCounts      *int64    `json:"max_query_counts"`
	MaxBytesTransferred *int64    `json:"max_bytes_transferred"`
}

CreateGrantRequest represents the request to create a grant

type CreateGrantRequestRequest added in v0.10.0 

type CreateGrantRequestRequest struct {
	GrantDefinitionID uuid.UUID `json:"grant_definition_id" binding:"required"`
	DatabaseID        uuid.UUID `json:"database_id" binding:"required"`
	Justification     string    `json:"justification"`
}

CreateGrantRequestRequest is the body for POST /grant-requests.

type CreateUserRequest 

type CreateUserRequest struct {
	Username string   `json:"username" binding:"required"`
	Password string   `json:"password" binding:"required"`
	Roles    []string `json:"roles"`
}

CreateUserRequest represents the request to create a user

type DatabaseLimitedResponse 

type DatabaseLimitedResponse struct {
	UID         uuid.UUID `json:"uid"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
}

DatabaseLimitedResponse represents a database with limited info (non-admin)

type DatabaseResponse 

type DatabaseResponse struct {
	UID               uuid.UUID  `json:"uid"`
	Name              string     `json:"name"`
	Description       string     `json:"description"`
	Host              string     `json:"host,omitempty"`
	Port              int        `json:"port,omitempty"`
	DatabaseName      string     `json:"database_name,omitempty"`
	Username          string     `json:"username,omitempty"`
	SSLMode           string     `json:"ssl_mode,omitempty"`
	Protocol          string     `json:"protocol,omitempty"`
	OracleServiceName string     `json:"oracle_service_name,omitempty"`
	CreatedBy         *uuid.UUID `json:"created_by,omitempty"`
}

DatabaseResponse represents a database with full details (admin only)

type DenyGrantRequestRequest added in v0.10.0 

type DenyGrantRequestRequest struct {
	Reason string `json:"reason"`
}

DenyGrantRequestRequest is the body for POST /grant-requests/:uid/deny.

type ErrorBody added in v0.4.0 

type ErrorBody struct {
	Code       ErrorCode `json:"code"`
	Message    string    `json:"message"`
	Detail     string    `json:"detail,omitempty"`
	RetryAfter int       `json:"retry_after,omitempty"`
}

ErrorBody is the standard error response structure.

type ErrorCode added in v0.4.0 

type ErrorCode string

ErrorCode is a machine-readable error code returned in API responses. 

const (
	// ErrCodeInternalError indicates an unexpected server error.
	ErrCodeInternalError ErrorCode = "INTERNAL_ERROR"
	// ErrCodeValidationError indicates invalid input.
	ErrCodeValidationError ErrorCode = "VALIDATION_ERROR"
	// ErrCodeNotFound indicates the requested resource was not found.
	ErrCodeNotFound ErrorCode = "NOT_FOUND"
	// ErrCodeUnauthorized indicates authentication is required.
	ErrCodeUnauthorized ErrorCode = "UNAUTHORIZED"
	// ErrCodeForbidden indicates insufficient permissions.
	ErrCodeForbidden ErrorCode = "FORBIDDEN"
	// ErrCodeInvalidCredentials indicates wrong username or password.
	ErrCodeInvalidCredentials ErrorCode = "INVALID_CREDENTIALS"
	// ErrCodePasswordChangeRequired indicates the user must change their password.
	ErrCodePasswordChangeRequired ErrorCode = "PASSWORD_CHANGE_REQUIRED"
	// ErrCodeWeakPassword indicates the password does not meet requirements.
	ErrCodeWeakPassword ErrorCode = "WEAK_PASSWORD"
	// ErrCodeRateLimited indicates too many requests.
	ErrCodeRateLimited ErrorCode = "RATE_LIMITED"
	// ErrCodeConflict indicates a state conflict (e.g. trying to transition
	// a non-pending grant request, or duplicating a unique resource).
	ErrCodeConflict ErrorCode = "CONFLICT"
	// ErrCodeOAuthFailed indicates an OAuth authentication failure.
	ErrCodeOAuthFailed ErrorCode = "OAUTH_FAILED"
	// ErrCodeOAuthStateMismatch indicates an invalid or expired OAuth state.
	ErrCodeOAuthStateMismatch ErrorCode = "OAUTH_STATE_MISMATCH"
	// ErrCodeOAuthProviderError indicates the OAuth provider returned an error.
	ErrCodeOAuthProviderError ErrorCode = "OAUTH_PROVIDER_ERROR"
	// ErrCodeOAuthUserNotLinked indicates no account is linked to the OAuth identity.
	ErrCodeOAuthUserNotLinked ErrorCode = "OAUTH_USER_NOT_LINKED"
	// ErrCodeOAuthWrongWorkspace indicates the wrong OAuth workspace was used.
	ErrCodeOAuthWrongWorkspace ErrorCode = "OAUTH_WRONG_WORKSPACE"
	// ErrCodeDuplicateName indicates a resource with that name already exists.
	ErrCodeDuplicateName ErrorCode = "DUPLICATE_NAME"
	// ErrCodeTargetMatchesSelf indicates the target matches the storage database.
	ErrCodeTargetMatchesSelf ErrorCode = "TARGET_MATCHES_SELF"
	// ErrCodeGrantExpired indicates the access grant has expired.
	ErrCodeGrantExpired ErrorCode = "GRANT_EXPIRED"
	// ErrCodeQuotaExceeded indicates a usage quota was exceeded.
	ErrCodeQuotaExceeded ErrorCode = "QUOTA_EXCEEDED"
)

type LoginRequest 

type LoginRequest struct {
	Username string `json:"username" binding:"required"`
	Password string `json:"password" binding:"required"`
}

LoginRequest represents the request body for login

type LoginResponse 

type LoginResponse struct {
	Token     string       `json:"token"`
	ExpiresAt string       `json:"expires_at"`
	User      UserResponse `json:"user"`
}

LoginResponse represents the response for a successful login

type MeResponse 

type MeResponse struct {
	UID                    string          `json:"uid"`
	Username               string          `json:"username"`
	Roles                  []string        `json:"roles"`
	PasswordChangeRequired bool            `json:"password_change_required"`
	Session                SessionResponse `json:"session"`
}

MeResponse represents the response for /auth/me

type PreLoginPasswordChangeRequest 

type PreLoginPasswordChangeRequest struct {
	Username        string `json:"username" binding:"required"`
	CurrentPassword string `json:"current_password" binding:"required"`
	NewPassword     string `json:"new_password" binding:"required"`
}

PreLoginPasswordChangeRequest represents the request body for pre-login password change

type RateLimiter 

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

RateLimiter implements a sliding window rate limiter

func NewRateLimiter 

func NewRateLimiter(cfg config.RateLimitConfig) *RateLimiter

NewRateLimiter creates a new rate limiter with the given configuration

func (*RateLimiter) GetStats 

func (rl *RateLimiter) GetStats(userID *uuid.UUID, ip string) (int, time.Time)

GetStats returns statistics for a given key (for testing/debugging)

func (*RateLimiter) Middleware 

func (rl *RateLimiter) Middleware() gin.HandlerFunc

Middleware returns a Gin middleware for rate limiting

func (*RateLimiter) PostAuthMiddleware 

func (rl *RateLimiter) PostAuthMiddleware() gin.HandlerFunc

PostAuthMiddleware is a rate limiter middleware that runs after authentication It uses the authenticated user ID for rate limiting

func (*RateLimiter) PreAuthMiddleware 

func (rl *RateLimiter) PreAuthMiddleware() gin.HandlerFunc

PreAuthMiddleware is a rate limiter middleware that runs before authentication It rate limits by IP for unauthenticated requests

type ResetPasswordRequest added in v0.3.0 

type ResetPasswordRequest struct {
	NewPassword string `json:"new_password" binding:"required"`
}

ResetPasswordRequest represents the request body for admin password reset

type Server 

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

Server represents the REST API server.

func NewServer 

func NewServer(dataStore *store.Store, encryptionKey []byte, logger *slog.Logger, cfg *config.Config) *Server

NewServer creates a new API server.

func (*Server) Shutdown 

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

Shutdown gracefully shuts down the server.

func (*Server) Start 

func (s *Server) Start(addr string) error

Start starts the API server.

type SessionResponse 

type SessionResponse struct {
	ExpiresAt string `json:"expires_at"`
	CreatedAt string `json:"created_at"`
}

SessionResponse represents session info in me response

type UpdateDatabaseRequest 

type UpdateDatabaseRequest struct {
	Description       *string `json:"description"`
	Host              *string `json:"host"`
	Port              *int    `json:"port"`
	DatabaseName      *string `json:"database_name"`
	Username          *string `json:"username"`
	Password          *string `json:"password"`
	SSLMode           *string `json:"ssl_mode"`
	Protocol          *string `json:"protocol"`
	OracleServiceName *string `json:"oracle_service_name"`
}

UpdateDatabaseRequest represents the request to update a database

type UpdateGrantDefinitionRequest added in v0.10.0 

type UpdateGrantDefinitionRequest = CreateGrantDefinitionRequest

UpdateGrantDefinitionRequest is the JSON body for PATCH /grant-definitions/:uid. The shape mirrors the create request — partial updates aren't worth the extra complexity for this small surface.

type UpdateUserRequest 

type UpdateUserRequest struct {
	Password *string  `json:"password"`
	Roles    []string `json:"roles"`
}

UpdateUserRequest represents the request to update a user

type UserResponse 

type UserResponse struct {
	UID                    string   `json:"uid"`
	Username               string   `json:"username"`
	Roles                  []string `json:"roles"`
	PasswordChangeRequired bool     `json:"password_change_required"`
}

UserResponse represents user info in login/me responses

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.