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 ¶
- Variables
- type APIReturnedUser
- type APITag
- type DefaultAPIResponse
- type DeleteJobAPIRequest
- type EditMetaRequest
- type ErrorResponse
- type GetClustersAPIResponse
- type GetCompleteJobAPIResponse
- type GetJobAPIRequest
- type GetJobAPIResponse
- type GetJobsAPIResponse
- type GetUsedNodesAPIResponse
- type JobMetaRequest
- type JobMetricWithName
- type LogEntry
- type NatsAPI
- type RestAPI
- type StopJobAPIRequest
- type TagJobAPIRequest
- type UpdateNodeStatesRequest
Constants ¶
This section is empty.
Variables ¶
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 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 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 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 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
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
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
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
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
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
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"`
}