api

package
v1.5.0 Latest Latest
Warning

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

Go to latest
Published: Mar 6, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package api Code generated by swaggo/swag. DO NOT EDIT

Copyright (C) NHR@FAU, University Erlangen-Nuremberg. All rights reserved. This file is part of cc-backend. Use of this source code is governed by a MIT-style license that can be found in the LICENSE file.

Package api provides the REST API layer for ClusterCockpit. It handles HTTP requests for job management, user administration, cluster queries, node state updates, and metrics storage operations. The API supports both JWT token authentication and session-based authentication.

Index

Constants

This section is empty.

Variables

View Source
var SwaggerInfo = &swag.Spec{
	Version:          "1.0.0",
	Host:             "localhost:8080",
	BasePath:         "",
	Schemes:          []string{},
	Title:            "ClusterCockpit REST API",
	Description:      "API for batch job control.",
	InfoInstanceName: "swagger",
	SwaggerTemplate:  docTemplate,
	LeftDelim:        "{{",
	RightDelim:       "}}",
}

SwaggerInfo holds exported Swagger Info so clients can modify it

Functions

This section is empty.

Types

type APIReturnedUser added in v1.5.0

type APIReturnedUser struct {
	Username string   `json:"username"`
	Name     string   `json:"name"`
	Roles    []string `json:"roles"`
	Email    string   `json:"email"`
	Projects []string `json:"projects"`
}

type APITag added in v1.5.0

type APITag struct {
	// Tag Type
	Type  string `json:"type" example:"Debug"`
	Name  string `json:"name" example:"Testjob"` // Tag Name
	Scope string `json:"scope" example:"global"` // Tag Scope for Frontend Display
}

APITag model

type DefaultAPIResponse added in v1.5.0

type DefaultAPIResponse struct {
	Message string `json:"msg"`
}

DefaultAPIResponse model

type DeleteJobAPIRequest added in v1.5.0

type DeleteJobAPIRequest struct {
	JobID     *int64  `json:"jobId" validate:"required" example:"123000"` // Cluster Job ID of job
	Cluster   *string `json:"cluster" example:"fritz"`                    // Cluster of job
	StartTime *int64  `json:"startTime" example:"1649723812"`             // Start Time of job as epoch
}

DeleteJobAPIRequest model

type EditMetaRequest added in v1.3.0

type EditMetaRequest struct {
	Key   string `json:"key" example:"jobScript"`
	Value string `json:"value" example:"bash script"`
}

type ErrorResponse

type ErrorResponse struct {
	// Statustext of Errorcode
	Status string `json:"status"`
	Error  string `json:"error"` // Error Message
}

ErrorResponse model

type GetClustersAPIResponse added in v1.5.0

type GetClustersAPIResponse struct {
	Clusters []*schema.Cluster `json:"clusters"` // Array of clusters
}

GetClustersAPIResponse model

type GetCompleteJobAPIResponse added in v1.5.0

type GetCompleteJobAPIResponse struct {
	Meta *schema.Job
	Data schema.JobData
}

type GetJobAPIRequest added in v1.5.0

type GetJobAPIRequest []string

type GetJobAPIResponse added in v1.5.0

type GetJobAPIResponse struct {
	Meta *schema.Job
	Data []*JobMetricWithName
}

type GetJobsAPIResponse added in v1.5.0

type GetJobsAPIResponse struct {
	Jobs  []*schema.Job `json:"jobs"`  // Array of jobs
	Items int           `json:"items"` // Number of jobs returned
	Page  int           `json:"page"`  // Page id returned
}

GetJobsAPIResponse model

type GetUsedNodesAPIResponse added in v1.5.0

type GetUsedNodesAPIResponse struct {
	UsedNodes map[string][]string `json:"usedNodes"` // Map of cluster names to lists of used node hostnames
}

GetUsedNodesAPIResponse model

type JobMetaRequest added in v1.5.0

type JobMetaRequest struct {
	JobId     *int64          `json:"jobId" validate:"required" example:"123000"` // Cluster Job ID of job
	Cluster   *string         `json:"cluster" example:"fritz"`                    // Cluster of job
	StartTime *int64          `json:"startTime" example:"1649723812"`             // Start Time of job as epoch
	Payload   EditMetaRequest `json:"payload"`                                    // Content to Add to Job Meta_Data
}

JobMetaRequest model

type JobMetricWithName

type JobMetricWithName struct {
	Metric *schema.JobMetric  `json:"metric"`
	Name   string             `json:"name"`
	Scope  schema.MetricScope `json:"scope"`
}

type LogEntry added in v1.5.0

type LogEntry struct {
	Timestamp string `json:"timestamp"`
	Priority  int    `json:"priority"`
	Message   string `json:"message"`
	Unit      string `json:"unit"`
}

type NatsAPI added in v1.5.0

type NatsAPI struct {
	JobRepository *repository.JobRepository
	// RepositoryMutex protects job creation operations from race conditions
	// when checking for duplicate jobs during startJob calls.
	RepositoryMutex sync.Mutex
}

NatsAPI provides NATS subscription-based handlers for Job and Node operations. It mirrors the functionality of the REST API but uses NATS messaging with InfluxDB line protocol as the message format.

Message Format

All NATS messages use InfluxDB line protocol format (https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol/) with the following structure:

measurement,tag1=value1,tag2=value2 field1=value1,field2=value2 timestamp

Job Events

Job start/stop events use the "job" measurement with a "function" tag to distinguish operations:

job,function=start_job event="{...JSON payload...}" <timestamp>
job,function=stop_job event="{...JSON payload...}" <timestamp>

The JSON payload in the "event" field follows the schema.Job or StopJobAPIRequest structure.

Example job start message:

job,function=start_job event="{\"jobId\":1001,\"user\":\"testuser\",\"cluster\":\"testcluster\",...}" 1234567890000000000

Node State Events

Node state updates use the "nodestate" measurement with cluster information:

nodestate event="{...JSON payload...}" <timestamp>

The JSON payload follows the UpdateNodeStatesRequest structure.

Example node state message:

nodestate event="{\"cluster\":\"testcluster\",\"nodes\":[{\"hostname\":\"node01\",\"states\":[\"idle\"]}]}" 1234567890000000000

func NewNatsAPI added in v1.5.0

func NewNatsAPI() *NatsAPI

NewNatsAPI creates a new NatsAPI instance with default dependencies.

func (*NatsAPI) StartSubscriptions added in v1.5.0

func (api *NatsAPI) StartSubscriptions() error

StartSubscriptions registers all NATS subscriptions for Job and Node APIs. Returns an error if the NATS client is not available or subscription fails.

type RestAPI added in v1.5.0

type RestAPI struct {
	JobRepository   *repository.JobRepository
	Authentication  *auth.Authentication
	MachineStateDir string
	// RepositoryMutex protects job creation operations from race conditions
	// when checking for duplicate jobs during startJob API calls.
	// It prevents concurrent job starts with the same jobId/cluster/startTime
	// from creating duplicate entries in the database.
	RepositoryMutex sync.Mutex
}

func New added in v1.4.0

func New() *RestAPI

New creates and initializes a new RestAPI instance with configured dependencies.

func (*RestAPI) MountAPIRoutes added in v1.5.0

func (api *RestAPI) MountAPIRoutes(r chi.Router)

MountAPIRoutes registers REST API endpoints for job and cluster management. These routes use JWT token authentication via the X-Auth-Token header.

func (*RestAPI) MountConfigAPIRoutes added in v1.5.0

func (api *RestAPI) MountConfigAPIRoutes(r chi.Router)

MountConfigAPIRoutes registers configuration and user management endpoints. These routes use session-based authentication and require admin privileges. Routes use full paths (including /config prefix) to avoid conflicting with the /config page route when registered via Group instead of Route.

func (*RestAPI) MountFrontendAPIRoutes added in v1.5.0

func (api *RestAPI) MountFrontendAPIRoutes(r chi.Router)

MountFrontendAPIRoutes registers frontend-specific API endpoints. These routes support JWT generation and user configuration updates with session authentication.

func (*RestAPI) MountMetricStoreAPIRoutes added in v1.5.0

func (api *RestAPI) MountMetricStoreAPIRoutes(r chi.Router)

MountMetricStoreAPIRoutes registers metric storage API endpoints. These endpoints handle metric data ingestion and health checks with JWT token authentication.

func (*RestAPI) MountUserAPIRoutes added in v1.5.0

func (api *RestAPI) MountUserAPIRoutes(r chi.Router)

MountUserAPIRoutes registers user-accessible REST API endpoints. These are limited endpoints for regular users with JWT token authentication.

type StopJobAPIRequest added in v1.5.0

type StopJobAPIRequest struct {
	JobID     *int64          `json:"jobId" example:"123000"`
	Cluster   *string         `json:"cluster" example:"fritz"`
	StartTime *int64          `json:"startTime" example:"1649723812"`
	State     schema.JobState `json:"jobState" validate:"required" example:"completed"`
	StopTime  int64           `json:"stopTime" validate:"required" example:"1649763839"`
}

StopJobAPIRequest model

type TagJobAPIRequest added in v1.5.0

type TagJobAPIRequest []*APITag

type UpdateNodeStatesRequest added in v1.5.0

type UpdateNodeStatesRequest struct {
	Nodes   []schema.NodePayload `json:"nodes"`
	Cluster string               `json:"cluster" example:"fritz"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL