api

package
v3.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2026 License: CC-BY-4.0, MIT Imports: 36 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ValidApplicationImageExt 

func ValidApplicationImageExt(ext string) bool

Types

type ApplicationAPI 

type ApplicationAPI struct {
	DB       ApplicationDatabase
	ImageDir string
}

The ApplicationAPI provides handlers for managing applications.

func (*ApplicationAPI) CreateApplication 

func (a *ApplicationAPI) CreateApplication(ctx *gin.Context)

CreateApplication creates an application and returns the access token. swagger:operation POST /application application createApp

Create an application. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the application to add
  required: true
  schema:
    $ref: "#/definitions/ApplicationParams"
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/Application"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*ApplicationAPI) DeleteApplication 

func (a *ApplicationAPI) DeleteApplication(ctx *gin.Context)

DeleteApplication deletes an application by its id. swagger:operation DELETE /application/{id} application deleteApp

Delete an application.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*ApplicationAPI) GetApplications 

func (a *ApplicationAPI) GetApplications(ctx *gin.Context)

GetApplications returns all applications a user has. swagger:operation GET /application application getApps

Return all applications. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
      type: array
      items:
        $ref: "#/definitions/Application"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*ApplicationAPI) RemoveApplicationImage 

func (a *ApplicationAPI) RemoveApplicationImage(ctx *gin.Context)

RemoveApplicationImage deletes an image of an application. swagger:operation DELETE /application/{id}/image application removeAppImage

Deletes an image of an application. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Server Error
    schema:
        $ref: "#/definitions/Error"

func (*ApplicationAPI) UpdateApplication 

func (a *ApplicationAPI) UpdateApplication(ctx *gin.Context)

UpdateApplication updates an application info by its id. swagger:operation PUT /application/{id} application updateApplication

Update an application. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the application to update
  required: true
  schema:
    $ref: "#/definitions/ApplicationParams"
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/Application"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*ApplicationAPI) UpdateApplicationSecurity 

func (a *ApplicationAPI) UpdateApplicationSecurity(ctx *gin.Context)

UpdateApplicationSecurity performs security updates on an application. swagger:operation PUT /application/{id}/security application updateAppSecurity

Perform security updates on an application.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: security update action descriptor
  required: true
  schema:
    $ref: "#/definitions/SecurityUpdateAction"
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/SecurityUpdateActionResponse"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Server Error
    schema:
        $ref: "#/definitions/Error"

func (*ApplicationAPI) UploadApplicationImage 

func (a *ApplicationAPI) UploadApplicationImage(ctx *gin.Context)

UploadApplicationImage uploads an image for an application. swagger:operation POST /application/{id}/image application uploadAppImage

Upload an image for an application. 

---
consumes:
- multipart/form-data
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: file
  in: formData
  description: the application image
  required: true
  type: file
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/Application"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Server Error
    schema:
        $ref: "#/definitions/Error"

type ApplicationDatabase 

type ApplicationDatabase interface {
	CreateApplication(application *model.Application) error
	GetApplicationByToken(token string) (*model.Application, error)
	GetApplicationByID(id uint) (*model.Application, error)
	GetApplicationsByUser(userID uint) ([]*model.Application, error)
	DeleteApplicationByID(id uint) error
	UpdateApplication(application *model.Application) error
}

The ApplicationDatabase interface for encapsulating database access.

type ApplicationParams 

type ApplicationParams struct {
	// The application name. This is how the application should be displayed to the user.
	//
	// required: true
	// example: Backup Server
	Name string `form:"name" query:"name" json:"name" binding:"required"`
	// The description of the application.
	//
	// example: Backup server for the interwebs
	Description string `form:"description" query:"description" json:"description"`
	// The default priority of messages sent by this application. Defaults to 0.
	//
	// example: 5
	DefaultPriority int `form:"defaultPriority" query:"defaultPriority" json:"defaultPriority"`
	// The sortKey for the application. Uses fractional indexing.
	//
	// example: a1
	SortKey string `form:"sortKey" query:"sortKey" json:"sortKey"`
}

Application Params Model

Params allowed to create or update Applications.

swagger:model ApplicationParams

type ClientAPI 

type ClientAPI struct {
	DB            ClientDatabase
	ImageDir      string
	NotifyDeleted func(uint, string)
}

The ClientAPI provides handlers for managing clients and applications.

func (*ClientAPI) CreateClient 

func (a *ClientAPI) CreateClient(ctx *gin.Context)

CreateClient creates a client and returns the access token. swagger:operation POST /client client createClient

Create a client. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the client to add
  required: true
  schema:
    $ref: "#/definitions/ClientParams"
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/Client"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*ClientAPI) DeleteClient 

func (a *ClientAPI) DeleteClient(ctx *gin.Context)

DeleteClient deletes a client by its id. swagger:operation DELETE /client/{id} client deleteClient

Delete a client.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the client id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*ClientAPI) ElevateClient 

func (a *ClientAPI) ElevateClient(ctx *gin.Context)

swagger:operation POST /client/{id}/elevate client elevateClient

Elevate a client session.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the client id
  required: true
  type: integer
  format: int64
- name: body
  in: body
  description: the elevation request
  required: true
  schema:
    $ref: "#/definitions/ElevateRequest"
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  204:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*ClientAPI) GetClients 

func (a *ClientAPI) GetClients(ctx *gin.Context)

GetClients returns all clients a user has. swagger:operation GET /client client getClients

Return all clients. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
      type: array
      items:
        $ref: "#/definitions/Client"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*ClientAPI) UpdateClient 

func (a *ClientAPI) UpdateClient(ctx *gin.Context)

UpdateClient updates a client by its id. swagger:operation PUT /client/{id} client updateClient

Update a client. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the client to update
  required: true
  schema:
    $ref: "#/definitions/ClientParams"
- name: id
  in: path
  description: the client id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/Client"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

type ClientDatabase 

type ClientDatabase interface {
	CreateClient(client *model.Client) error
	GetClientByToken(token string) (*model.Client, error)
	GetClientByID(id uint) (*model.Client, error)
	GetClientsByUser(userID uint) ([]*model.Client, error)
	DeleteClientByID(id uint) error
	UpdateClient(client *model.Client) error
	UpdateClientElevatedUntil(id uint, t *time.Time) error
}

The ClientDatabase interface for encapsulating database access.

type ClientParams 

type ClientParams struct {
	// The client name
	//
	// required: true
	// example: My Client
	Name string `form:"name" query:"name" json:"name" binding:"required"`
	// The number of seconds of inactivity after which the client is removed.
	// 0 (or omitted) means the client never expires.
	//
	// example: 2592000
	ExpiresAfterInactivitySeconds *uint `form:"expiresAfterInactivitySeconds" query:"expiresAfterInactivitySeconds" json:"expiresAfterInactivitySeconds"`
}

Client Params Model

Params allowed to create or update Clients.

swagger:model ClientParams

type HealthAPI 

type HealthAPI struct {
	DB HealthDatabase
}

The HealthAPI provides handlers for the health information.

func (*HealthAPI) Health 

func (a *HealthAPI) Health(ctx *gin.Context)

Health returns health information. swagger:operation GET /health info getHealth

Get health information. 

---
produces: [application/json]
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/Health"
  500:
    description: Ok
    schema:
        $ref: "#/definitions/Health"

type HealthDatabase 

type HealthDatabase interface {
	Ping() error
}

The HealthDatabase interface for encapsulating database access.

type MessageAPI 

type MessageAPI struct {
	DB       MessageDatabase
	Notifier Notifier
}

The MessageAPI provides handlers for managing messages.

func (*MessageAPI) CreateMessage 

func (a *MessageAPI) CreateMessage(ctx *gin.Context)

CreateMessage creates a message, authentication via application token, client token, or basic auth is required. swagger:operation POST /message message createMessage

Create a message.

__NOTE__: When authenticating with a client token or basic auth, the request body must include "appid" referencing an application owned by the authenticated user. When authenticating with an application token, the application is derived from the token and any "appid" in the body is ignored. 

---
consumes: [application/json]
produces: [application/json]
security: [appTokenAuthorizationHeader: [], appTokenHeader: [], appTokenQuery: [], clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the message to add
  required: true
  schema:
    $ref: "#/definitions/CreateMessage"
responses:
  200:
    description: Ok
    schema:
      $ref: "#/definitions/Message"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*MessageAPI) DeleteMessage 

func (a *MessageAPI) DeleteMessage(ctx *gin.Context)

DeleteMessage deletes a message with an id. swagger:operation DELETE /message/{id} message deleteMessage

Deletes a message with an id. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: id
  in: path
  description: the message id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*MessageAPI) DeleteMessageWithApplication 

func (a *MessageAPI) DeleteMessageWithApplication(ctx *gin.Context)

DeleteMessageWithApplication deletes all messages from a specific application. swagger:operation DELETE /application/{id}/message message deleteAppMessages

Delete all messages from a specific application. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*MessageAPI) DeleteMessages 

func (a *MessageAPI) DeleteMessages(ctx *gin.Context)

DeleteMessages delete all messages from a user. swagger:operation DELETE /message message deleteMessages

Delete all messages. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*MessageAPI) GetMessages 

func (a *MessageAPI) GetMessages(ctx *gin.Context)

GetMessages returns all messages from a user. swagger:operation GET /message message getMessages

Return all messages. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: limit
  in: query
  description: the maximal amount of messages to return
  required: false
  maximum: 200
  minimum: 1
  default: 100
  type: integer
- name: since
  in: query
  description: return all messages with an ID less than this value
  minimum: 0
  required: false
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/PagedMessages"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*MessageAPI) GetMessagesWithApplication 

func (a *MessageAPI) GetMessagesWithApplication(ctx *gin.Context)

GetMessagesWithApplication returns all messages from a specific application. swagger:operation GET /application/{id}/message message getAppMessages

Return all messages from a specific application. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: id
  in: path
  description: the application id
  required: true
  type: integer
  format: int64
- name: limit
  in: query
  description: the maximal amount of messages to return
  required: false
  maximum: 200
  minimum: 1
  default: 100
  type: integer
- name: since
  in: query
  description: return all messages with an ID less than this value
  minimum: 0
  required: false
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/PagedMessages"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

type MessageDatabase 

type MessageDatabase interface {
	GetMessagesByApplicationSince(appID uint, limit int, since uint) ([]*model.Message, error)
	GetApplicationByID(id uint) (*model.Application, error)
	GetMessagesByUserSince(userID uint, limit int, since uint) ([]*model.Message, error)
	DeleteMessageByID(id uint) error
	GetMessageByID(id uint) (*model.Message, error)
	DeleteMessagesByUser(userID uint) error
	DeleteMessagesByApplication(applicationID uint) error
	CreateMessage(message *model.Message) error
}

The MessageDatabase interface for encapsulating database access.

type Notifier 

type Notifier interface {
	Notify(userID uint, message *model.MessageExternal)
}

Notifier notifies when a new message was created.

type OIDCAPI 

type OIDCAPI struct {
	DB                 *database.GormDatabase
	Provider           rp.RelyingParty
	UserChangeNotifier *UserChangeNotifier
	UsernameClaim      string
	GroupsClaim        string
	GroupsUser         []string
	GroupsAdmin        []string
	PasswordStrength   int
	SecureCookie       bool
	AutoRegister       bool
	LinkByUsername     bool
	Prompt             []string
	// contains filtered or unexported fields
}

OIDCAPI provides handlers for OIDC authentication.

func NewOIDC 

func NewOIDC(conf *config.Configuration, db *database.GormDatabase, userChangeNotifier *UserChangeNotifier) *OIDCAPI

func (*OIDCAPI) CallbackHandler 

func (a *OIDCAPI) CallbackHandler() gin.HandlerFunc

swagger:operation GET /auth/oidc/callback oidc oidcCallback

Handle the OIDC provider callback (browser).

Exchanges the authorization code for tokens, resolves the user, creates a gotify client, sets a session cookie, and redirects to the UI. 

---
parameters:
- name: code
  in: query
  description: the authorization code from the OIDC provider
  required: true
  type: string
- name: state
  in: query
  description: the state parameter for CSRF protection
  required: true
  type: string
responses:
  200:
    description: ok
  307:
    description: Redirect to UI
  default:
    description: Error
    schema:
        $ref: "#/definitions/Error"

func (*OIDCAPI) ElevateHandler 

func (a *OIDCAPI) ElevateHandler(ctx *gin.Context)

swagger:operation GET /auth/oidc/elevate oidc oidcElevate

Start the OIDC flow to elevate an existing client session (browser).

Redirects the user to the OIDC provider's authorization endpoint. After successful authentication, the referenced client session is elevated for the requested duration. 

---
parameters:
- name: id
  in: query
  description: the client id to elevate
  required: true
  type: integer
  format: int64
- name: durationSeconds
  in: query
  description: how long the elevation should last, in seconds
  required: true
  type: integer
responses:
  302:
    description: Redirect to OIDC provider
  default:
    description: Error
    schema:
        $ref: "#/definitions/Error"

func (*OIDCAPI) ExternalAuthorizeHandler 

func (a *OIDCAPI) ExternalAuthorizeHandler(ctx *gin.Context)

swagger:operation POST /auth/oidc/external/authorize oidc externalAuthorize

Initiate the OIDC authorization flow for a native app.

The app generates a PKCE code_verifier and code_challenge, then calls this endpoint. The server forwards the code_challenge to the OIDC provider and returns the authorization URL for the app to open in a browser. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: body
  in: body
  required: true
  schema:
    $ref: "#/definitions/OIDCExternalAuthorizeRequest"
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/OIDCExternalAuthorizeResponse"
  default:
    description: Error
    schema:
        $ref: "#/definitions/Error"

func (*OIDCAPI) ExternalTokenHandler 

func (a *OIDCAPI) ExternalTokenHandler(ctx *gin.Context)

swagger:operation POST /auth/oidc/external/token oidc externalToken

Exchange an authorization code for a gotify client token.

After the user authenticates with the OIDC provider and the app receives the authorization code via redirect, the app calls this endpoint with the code and PKCE code_verifier. The server exchanges the code with the OIDC provider and returns a gotify client token. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: body
  in: body
  required: true
  schema:
    $ref: "#/definitions/OIDCExternalTokenRequest"
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/OIDCExternalTokenResponse"
  default:
    description: Error
    schema:
        $ref: "#/definitions/Error"

func (*OIDCAPI) LoginHandler 

func (a *OIDCAPI) LoginHandler() gin.HandlerFunc

swagger:operation GET /auth/oidc/login oidc oidcLogin

Start the OIDC login flow (browser).

Redirects the user to the OIDC provider's authorization endpoint. After authentication, the provider redirects back to the callback endpoint. 

---
parameters:
- name: name
  in: query
  description: the client name to create after login
  required: true
  type: string
responses:
  302:
    description: Redirect to OIDC provider
  default:
    description: Error
    schema:
        $ref: "#/definitions/Error"

type PluginAPI 

type PluginAPI struct {
	Notifier Notifier
	Manager  *plugin.Manager
	DB       PluginDatabase
}

The PluginAPI provides handlers for managing plugins.

func (*PluginAPI) DisablePlugin 

func (c *PluginAPI) DisablePlugin(ctx *gin.Context)

DisablePlugin disables a plugin. swagger:operation POST /plugin/{id}/disable plugin disablePlugin

Disable a plugin. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the plugin id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Internal Server Error
    schema:
        $ref: "#/definitions/Error"

func (*PluginAPI) EnablePlugin 

func (c *PluginAPI) EnablePlugin(ctx *gin.Context)

EnablePlugin enables a plugin. swagger:operation POST /plugin/{id}/enable plugin enablePlugin

Enable a plugin. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the plugin id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Internal Server Error
    schema:
        $ref: "#/definitions/Error"

func (*PluginAPI) GetConfig 

func (c *PluginAPI) GetConfig(ctx *gin.Context)

GetConfig returns Configurer plugin configuration in YAML format. swagger:operation GET /plugin/{id}/config plugin getPluginConfig

Get YAML configuration for Configurer plugin. 

---
consumes: [application/json]
produces: [application/x-yaml]
parameters:
- name: id
  in: path
  description: the plugin id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
        type: object
        description: plugin configuration
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Internal Server Error
    schema:
        $ref: "#/definitions/Error"

func (*PluginAPI) GetDisplay 

func (c *PluginAPI) GetDisplay(ctx *gin.Context)

GetDisplay get display info for Displayer plugin. swagger:operation GET /plugin/{id}/display plugin getPluginDisplay

Get display info for a Displayer plugin. 

---
consumes: [application/json]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the plugin id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
      type: string
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Internal Server Error
    schema:
        $ref: "#/definitions/Error"

func (*PluginAPI) GetPlugins 

func (c *PluginAPI) GetPlugins(ctx *gin.Context)

GetPlugins returns all plugins a user has. swagger:operation GET /plugin plugin getPlugins

Return all plugins. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
      type: array
      items:
        $ref: "#/definitions/PluginConf"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Internal Server Error
    schema:
        $ref: "#/definitions/Error"

func (*PluginAPI) UpdateConfig 

func (c *PluginAPI) UpdateConfig(ctx *gin.Context)

UpdateConfig updates Configurer plugin configuration in YAML format. swagger:operation POST /plugin/{id}/config plugin updatePluginConfig

Update YAML configuration for Configurer plugin. 

---
consumes: [application/x-yaml]
produces: [application/json]
parameters:
- name: id
  in: path
  description: the plugin id
  required: true
  type: integer
  format: int64
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"
  500:
    description: Internal Server Error
    schema:
        $ref: "#/definitions/Error"

type PluginDatabase 

type PluginDatabase interface {
	GetPluginConfByUser(userid uint) ([]*model.PluginConf, error)
	UpdatePluginConf(p *model.PluginConf) error
	GetPluginConfByID(id uint) (*model.PluginConf, error)
}

The PluginDatabase interface for encapsulating database access.

type SessionAPI 

type SessionAPI struct {
	DB               SessionDatabase
	NotifyDeleted    func(uint, string)
	SecureCookie     bool
	LocalAuthEnabled bool
}

SessionAPI provides handlers for cookie-based session authentication.

func (*SessionAPI) Login 

func (a *SessionAPI) Login(ctx *gin.Context)

swagger:operation POST /auth/local/login auth localLogin

Authenticate via basic auth and create a session. 

---
consumes: [application/x-www-form-urlencoded]
produces: [application/json]
security:
- basicAuth: []
parameters:
- name: name
  in: formData
  description: the client name to create
  required: true
  type: string
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/CurrentUser"
    headers:
      Set-Cookie:
        type: string
        description: session cookie
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*SessionAPI) Logout 

func (a *SessionAPI) Logout(ctx *gin.Context)

swagger:operation POST /auth/logout auth logout

End the current session.

Clears the session cookie and deletes the associated client. 

---
produces: [application/json]
security:
- clientTokenHeader: []
- clientTokenQuery: []
- basicAuth: []
responses:
  200:
    description: Ok
    headers:
      Set-Cookie:
        type: string
        description: cleared session cookie
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"

type SessionDatabase 

type SessionDatabase interface {
	GetUserByName(name string) (*model.User, error)
	CreateClient(client *model.Client) error
	GetClientByToken(token string) (*model.Client, error)
	DeleteClientByID(id uint) error
}

SessionDatabase is the interface for session-related database access.

type UserAPI 

type UserAPI struct {
	DB                 UserDatabase
	PasswordStrength   int
	UserChangeNotifier *UserChangeNotifier
	Registration       bool
}

The UserAPI provides handlers for managing users.

func (*UserAPI) ChangePassword 

func (a *UserAPI) ChangePassword(ctx *gin.Context)

ChangePassword changes the password from the current user swagger:operation POST /current/user/password user updateCurrentUser

Update the password of the current user.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the user
  required: true
  schema:
    $ref: "#/definitions/UserPass"
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*UserAPI) CreateUser 

func (a *UserAPI) CreateUser(ctx *gin.Context)

CreateUser create a user. swagger:operation POST /user user createUser

Create a user.

With enabled registration: non admin users can be created without authentication. With disabled registrations: users can only be created by admin users.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: body
  in: body
  description: the user to add
  required: true
  schema:
    $ref: "#/definitions/CreateUserExternal"
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/User"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*UserAPI) DeleteUserByID 

func (a *UserAPI) DeleteUserByID(ctx *gin.Context)

DeleteUserByID deletes the user by id swagger:operation DELETE /user/{id} user deleteUser

Deletes a user.

Requires elevated authentication. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: id
  in: path
  description: the user id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*UserAPI) GetCurrentUser 

func (a *UserAPI) GetCurrentUser(ctx *gin.Context)

GetCurrentUser returns the current user swagger:operation GET /current/user user currentUser

Return the current user.

Requires elevated authentication. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/User"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*UserAPI) GetUserByID 

func (a *UserAPI) GetUserByID(ctx *gin.Context)

GetUserByID returns the user by id swagger:operation GET /user/{id} user getUser

Get a user.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: id
  in: path
  description: the user id
  required: true
  type: integer
  format: int64
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/User"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

func (*UserAPI) GetUsers 

func (a *UserAPI) GetUsers(ctx *gin.Context)

GetUsers returns all the users swagger:operation GET /user user getUsers

Return all users.

Requires elevated authentication. 

---
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
responses:
  200:
    description: Ok
    schema:
      type: array
      items:
        $ref: "#/definitions/User"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"

func (*UserAPI) UpdateUserByID 

func (a *UserAPI) UpdateUserByID(ctx *gin.Context)

UpdateUserByID updates and user by id swagger:operation POST /user/{id} user updateUser

Update a user.

Requires elevated authentication. 

---
consumes: [application/json]
produces: [application/json]
security: [clientTokenAuthorizationHeader: [], clientTokenHeader: [], clientTokenQuery: [], basicAuth: []]
parameters:
- name: id
  in: path
  description: the user id
  required: true
  type: integer
  format: int64
- name: body
  in: body
  description: the updated user
  required: true
  schema:
    $ref: "#/definitions/UpdateUserExternal"
responses:
  200:
    description: Ok
    schema:
        $ref: "#/definitions/User"
  400:
    description: Bad Request
    schema:
        $ref: "#/definitions/Error"
  401:
    description: Unauthorized
    schema:
        $ref: "#/definitions/Error"
  403:
    description: Forbidden
    schema:
        $ref: "#/definitions/Error"
  404:
    description: Not Found
    schema:
        $ref: "#/definitions/Error"

type UserChangeNotifier 

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

UserChangeNotifier notifies listeners for user changes.

func (*UserChangeNotifier) OnUserAdded 

func (c *UserChangeNotifier) OnUserAdded(cb func(uid uint) error)

OnUserAdded is called on user creation.

func (*UserChangeNotifier) OnUserDeleted 

func (c *UserChangeNotifier) OnUserDeleted(cb func(uid uint) error)

OnUserDeleted is called on user deletion.

type UserDatabase 

type UserDatabase interface {
	GetUsers() ([]*model.User, error)
	GetUserByID(id uint) (*model.User, error)
	GetUserByName(name string) (*model.User, error)
	DeleteUserByID(id uint) error
	UpdateUser(user *model.User) error
	CreateUser(user *model.User) error
	CountUser(condition ...any) (int64, error)
}

The UserDatabase interface for encapsulating database access.

Source Files

View all Source files

Directories

Path Synopsis

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.