clu

package module
v0.0.0-...-46d79ed Latest Latest
Warning

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

Go to latest
Published: Feb 9, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

README

Clu REST API

Introduction

This application named CluAPI is a generic database interface REST server. It can be used to query, search and modify database data. There is no complex infrastructure inbetween, a direct connection to the database. A mechanism of authentication and authorization exists inbetween REST query and database access. Some predefined database queries can be defined in an batch database record. The batch queries can be defined providing extra rest parameters. That's different to standard database views.

There should be no difference if the database is a SQL or a NoSQL database.

A list of data records should be able to be inserted or updated in one REST API call. May be as transaction or in an atomic matter.

Based on database layer Flynn at https://github.com/tknie/flynn the database is queryed and updated.

  • Read, Search, Insert, Update and Delete of data records
  • Search by passing database specific queries to be flexible for complex queries
  • Large object support of big data
    • binary data queries
    • image data queries
    • video data queries
  • Support creating batch jobs for database-specific tasks like SQL scripts or a complex query

For possible detailed information about the Flynn layer, have a look at the API documentation. It can be referenced here: https://godoc.org/github.com/tknie/flynn

Release information

The version 1.0.0 is released. It is a stable version used for various projects giving access to audit data stored in the database. It is stable and no problem known. You can download the Docker image at https://hub.docker.com/r/thknie/cluapi or download it in Docker/Podman with

docker pull thknie/cluapi

Authentication

There are several possibilities to use authentication

  • Create a realm file containing user and password
  • Use system user and password to authenticate
  • Using LDAP password authentication
  • Using a SQL query to authenticate using the SQL database

All these configuration are used from https://github.com/tknie/services.

Authorization

You can use database roles and users authorization restriction if you use database users management. CluAPI provides a query entry role management to obmit user specific queries for read- or write-access. In addition you can define authorization access to some resources like tables or views.

For example in users.yaml you can define read or write restriction for table, views or batch scripts

  • all tables and views are restricted using to prefix
  • the prefix ^ restrict to batch processing tasks or complex queries
  • the prefix < allows read/download file permissions
  • the prefix > allows write/upload file permissions

Batch store usage

You can define some predefined queries which are generated using the parameters given in an REST request.

Detail documentation about Batch store definition is found here.

Example of Clu usage

Query records in database
Accept: application/json
Authorization: Base <base64>
GET http://localhost:8030/rest/view/Albums/ID,Title,published?limit=0&orderby=published:ASC
Update records in database
Accept: application/json
Authorization: Base <base64>
PUT http://localhost:8030/rest/view/Albums/ID,Title,published?limit=0&orderby=published:ASC
 {
  "Records": [
    {
      "id": "18",
      "title": "Der Ostergruss"
    },
 }
Insert records in database
Accept: application/json
Authorization: Base <base64>
PUSH http://localhost:8030/rest/view/Albums/ID,Title,published?limit=0&orderby=published:ASC

REST API information

To evaluate the REST API look at Swagger Editor with clu REST API informations.

Download/Upload files

To exchange files into local file system like logs or extra information it is possible to upload or download files from a specific location.

Below a download location is defined which can be referenced using the download path.

fileTransfer:
  Admin:
    role: xxx
  directories:
    directory:
      - name: download
        location: ${HOME}/Downloads
      - name: tmp
        location: ${CURDIR}/tmp

Check List

Feature Ready-State Description
Login database Draft
Query record Draft
Search record Draft
Insert record Draft
Delete record Draft
Load images out of database Draft
Load videos out of database Draft
Load binaries out of database Draft
Insert Large Object (Image, binary or others) Draft (not recommended if images is to big)
Create table Draft
Insert database Draft
Work with predefined batch queries Draft
Complex search queries (common to SQL or NonSQL databases) planned

Documentation

Index

Constants

View Source
const (
	// DefaultConfigFileEnv default environment name to search configuration file at
	DefaultConfigFileEnv = "SERVER_CONFIG"
	// InstallationDirName directory name of product installation location
	InstallationDirName = "."
	// ServiceName servoce name of product
	ServiceName = "clutronapi"
)
View Source
const DefaultRole = "Reader"

DefaultRole default role for automatic added user

Variables

View Source
var AddLocation = func(name, location string) error {
	if name != "" && os.ExpandEnv(location) != "" {
		services.ServerMessage("Add location %s at %s", name, location)
	}
	return nil
}

AddLocation add location, only needed in active server

View Source
var Audit func(time.Time, *http.Request, error)

Audit callback function to be enabled

View Source
var CurrentConfig = ""

CurrentConfig current config name

View Source
var DeleteUUID = false

DeleteUUID delete UUID after regular time frame

View Source
var InitAdmin func(*RestServer)

InitAdmin init Adabas admin function, only need in active server

View Source
var InitDirectAccess func(*RestServer)

InitDirectAccess init Adabas direct access function, only need in active server

Functions

func AddUserInfo

func AddUserInfo(userInfo *auth.UserInfo) error

AddUserInfo add user if not already exists and create if not available

func CheckDatabaseRegister

func CheckDatabaseRegister(s string, id *common.Reference) bool

CheckDatabaseRegister check database register

func CheckUserExist

func CheckUserExist(user string) *auth.UserInfo

CheckUserExist check user already exists and create if not available

func DumpStat

func DumpStat()

DumpStat dump database access statistics to log

func GetAdaDataDir

func GetAdaDataDir() string

GetAdaDataDir get ADADATADIR configuration

func GetAllViews

func GetAllViews() []string

GetAllViews get all table and view names

func GetInstallation

func GetInstallation() []string

GetInstallation get defined installations

func InitBatchRepository

func InitBatchRepository(dbRef *common.Reference, dbPassword, tablename string) bool

InitBatchRepository init batch repository

func InitBatchWatcherThread

func InitBatchWatcherThread()

InitBatchWatcherThread initialize batch watcher

func InitStoreInfo

func InitStoreInfo(ref *common.Reference, password, tablename string)

InitStoreInfo init session info storage

func InitUserInfo

func InitUserInfo(ref *common.Reference, password, tablename string)

InitUserInfo init user info evaluation

func LoadConfig

func LoadConfig(watch bool, loaderInterface services.ConfigInterface) error

LoadConfig load xml configuration file The components are used to load and inject the configuration

func LoadMessages

func LoadMessages()

LoadMessages load all REST server embed message templates

func LoadedConfig

func LoadedConfig()

LoadedConfig triggered by configuration load

func QueryUser

func QueryUser(user string) *auth.UserInfo

QueryUser query user information

func RegisterConfigUpdates

func RegisterConfigUpdates(f func())

RegisterConfigUpdates register configuration trigger function

Types

type Admin

type Admin struct {
	Role           string `yaml:"role,omitempty"`
	UseRole        bool   `yaml:"use_role,omitempty"`
	NoModification bool   `yaml:"NoModification,omitempty"`
}

Admin suite installation

type BatchEntry

type BatchEntry struct {
	Name       string
	Query      string `flynn:":BLOB"`
	Database   string
	ParamCount int
}

BatchEntry entry of batch repository

func BatchSelect

func BatchSelect(batchname string) (*BatchEntry, error)

BatchSelect search for batchname in an batch repository

type CommonConfig

type CommonConfig struct {
	Version             string `yaml:"version"`
	ConfigWatcher       bool   `yaml:"configWatcher,omitempty"`
	MaxBinaryBufferSize int    `yaml:"maxBinaryBufferSize,omitempty"`
	StatisticTimer      bool   `yaml:"statisticTimer,omitempty"`
	AppURL              string `yaml:"AppURL,omitempty"`
}

CommonConfig server config base

type Context

type Context struct {

	// User string
	Pass string
	Auth struct {
		Roles   []string
		Remote  string
		Session interface{}
	}
	Token string

	CurrentRequest *http.Request
	// contains filtered or unexported fields
}

Context server context

func NewContext deprecated

func NewContext(user, pass string) *Context

NewContext new server context with user and password

Deprecated: Use NewContextUserInfo instead

func NewContextUserInfo

func NewContextUserInfo(userInfo *auth.UserInfo, pass string) *Context

NewContextUserInfo new server context with user information and password

func (*Context) AddRoles

func (sc *Context) AddRoles(r []string)

AddRoles add roles interface function

func (*Context) Created

func (sc *Context) Created() time.Time

Created context creation time

func (*Context) Deadline

func (sc *Context) Deadline() (deadline time.Time, ok bool)

Deadline dead line

func (*Context) Done

func (sc *Context) Done() <-chan struct{}

Done context done

func (*Context) EMail

func (sc *Context) EMail() string

EMail email for this user

func (*Context) Err

func (sc *Context) Err() error

Err error return

func (*Context) GetData

func (sc *Context) GetData(key string) any

GetData entry specific storage of data is requested

func (*Context) LastLogin

func (sc *Context) LastLogin() time.Time

LastLogin last login of user

func (*Context) LongName

func (sc *Context) LongName() string

LongName long name of user

func (*Context) Name

func (sc *Context) Name() string

Name Name interface function

func (*Context) Permission

func (sc *Context) Permission() *auth.User

Permission return user permission

func (*Context) Picture

func (sc *Context) Picture() string

Picture thumbnail picture store [optional]

func (*Context) Remote

func (sc *Context) Remote() string

Remote remote info interface function

func (*Context) Roles

func (sc *Context) Roles() []string

Roles roles info interface function

func (*Context) SendAuditError

func (sc *Context) SendAuditError(started time.Time, err error)

SendAuditError send audit error in context

func (*Context) Session

func (sc *Context) Session() interface{}

Session session info interface function

func (*Context) SetLongName

func (sc *Context) SetLongName(longName string)

SetLongName set long name of user

func (*Context) SetRemote

func (sc *Context) SetRemote(r string)

SetRemote set remote info interface function

func (*Context) SetSession

func (sc *Context) SetSession(s interface{})

SetSession set session info interface function

func (*Context) StoreData

func (sc *Context) StoreData(key string, value any)

StoreData entry specific storage of data

func (*Context) UUID

func (sc *Context) UUID() string

UUID UUID interface function

func (*Context) UpdateLastLogin

func (sc *Context) UpdateLastLogin()

UpdateLastLogin set last login of user

func (*Context) User

func (sc *Context) User() *auth.UserInfo

User return user information

func (*Context) UserName

func (sc *Context) UserName() string

UserName user interface function

func (*Context) Value

func (sc *Context) Value(key any) any

Value value of key

type Database

type Database struct {
	Driver               string   `yaml:"driver"`
	User                 string   `yaml:"user,omitempty"`
	Password             string   `yaml:"password,omitempty"`
	Target               string   `yaml:"target,omitempty"`
	Table                string   `yaml:"table,omitempty"`
	Tables               []string `yaml:"tables,omitempty"`
	Enabled              bool     `yaml:"enabled,omitempty"`
	AuthenticationGlobal bool     `yaml:"global_authentication,omitempty"`
}

Database database

func (*Database) Handles

func (db *Database) Handles() (*common.Reference, error)

Handles handle database

func (*Database) RegisterDatabase

func (db *Database) RegisterDatabase(s string, id *common.Reference) bool

RegisterDatabase register database for table

func (*Database) String

func (db *Database) String() string

String representation of Database instance

type DatabaseAccess

type DatabaseAccess struct {
	Global   bool       `yaml:"global,omitempty"`
	Database []Database `yaml:"databases,omitempty"`
}

DatabaseAccess database access

type DatabaseConfig

type DatabaseConfig struct {
	Mapping         Mapping        `yaml:"modelling"`
	DatabaseAccess  DatabaseAccess `yaml:"access"`
	SessionInfo     *SessionConfig `yaml:"sessionInfo"`
	UserInfo        *Database      `yaml:"userInfo"`
	BatchRepository *Database      `yaml:"batchRepository"`
}

DatabaseConfig database modelling and access

type DatabaseMap

type DatabaseMap struct {
	Name        string `yaml:"Name"`
	SrcDatabase string `yaml:"Database"`
	SQL         string `yaml:"SQL"`
	SrcTable    string `yaml:"SourceTable"`
	SrcField    string `yaml:"SourceField"`
	DestTable   string `yaml:"DestinationTable"`
	DestField   string `yaml:"DestinationField"`
}

DatabaseMap database modelling configuration

type DatabaseRegister

type DatabaseRegister struct {
	Reference *common.Reference
	Database  *Database
	// contains filtered or unexported fields
}

DatabaseRegister database register

func SearchTable

func SearchTable(table string) (*DatabaseRegister, error)

SearchTable search table ref ID

type Directory

type Directory struct {
	Name     string `yaml:"name"`
	Location string `yaml:"location"`
}

Directory directory entries

type ErrorType

type ErrorType byte

ErrorType web request return type

const (
	// Ok web response Ok
	Ok ErrorType = iota
	// BadRequest web response bad request
	BadRequest
)

type FileTransferConfig

type FileTransferConfig struct {
	Admin       Admin `yaml:"Admin"`
	Directories struct {
		Role      string      `yaml:"role,omitempty"`
		UseRole   bool        `yaml:"use_role,omitempty"`
		Directory []Directory `yaml:"directory"`
	} `yaml:"directories"`
}

FileTransferConfig file transfer config

type Location

type Location struct {
	Location string `yaml:"location"`
}

Location location attribute

type LoginService

type LoginService struct {
	Type                 string                       `yaml:"type,omitempty"`
	Module               string                       `yaml:"module,omitempty"`
	Administrators       string                       `yaml:"administrators,omitempty"`
	Users                string                       `yaml:"users,omitempty"`
	AuthenticationServer []*auth.AuthenticationServer `yaml:"authenticationServer,omitempty"`
}

LoginService login service

type Mapping

type Mapping struct {
	CacheUpdater int           `yaml:"cacheTimer,omitempty"`
	DatabaseMap  []DatabaseMap `yaml:"Modeling"`
}

Mapping Adabas Maps

type RestServer

type RestServer struct {
	Common       CommonConfig       `yaml:"rest-server"`
	Server       Server             `yaml:"server"`
	Database     DatabaseConfig     `yaml:"database"`
	Tasks        TaskConfig         `yaml:"tasks"`
	FileTransfer FileTransferConfig `yaml:"fileTransfer"`
	Metrics      []*Database
}

RestServer Rest server main node configuration structure containing all referenced parameters reflected to the configuration file.

var Viewer *RestServer

Viewer containing server config

func (*RestServer) CloseConfig

func (viewer *RestServer) CloseConfig()

CloseConfig close configuration watcher

func (*RestServer) InitSecurityInfrastructure

func (viewer *RestServer) InitSecurityInfrastructure()

InitSecurityInfrastructure init configruation data

type Server

type Server struct {
	Service      []*Service        `yaml:"service"`
	WebToken     *auth.WebToken    `yaml:"JWT,omitempty"`
	LoginService LoginService      `yaml:"login"`
	Prefix       string            `yaml:"prefix,omitempty"`
	Content      string            `yaml:"content,omitempty"`
	Plugins      string            `yaml:"plugins,omitempty"`
	LogLocation  *services.Logging `yaml:"location"`
	Shutdown     struct {
		Passcode yaml.Node `yaml:"passcode,omitempty"`
	} `yaml:"shutdown"`
}

Server REST server main configuration parameter

type Service

type Service struct {
	Host              string           `yaml:"host"`
	Port              int              `yaml:"port"`
	Type              string           `yaml:"type"`
	Certificate       string           `yaml:"certificate,omitempty"`
	Key               string           `yaml:"key,omitempty"`
	MaxHeaderSize     flagext.ByteSize `yaml:"maxHeaderSize"`
	ReadTimeout       time.Duration    `yaml:"readTimeout"`
	WriteTimeout      time.Duration    `yaml:"writeTimeout"`
	KeepAlive         int              `yaml:"keepAive"`
	ListenLimit       int              `yaml:"listenLimit"`
	CleanupTimeout    time.Duration    `yaml:"cleanupTimeout"`
	TLSCACertificate  string           `yaml:"TLSCaCertificate"`
	TLSCertificate    string
	TLSCertificateKey string
}

Service service entry

type SessionConfig

type SessionConfig struct {
	DeleteUUID bool      `yaml:"deleteUUID"`
	Database   *Database `yaml:"database"`
}

SessionConfig session configuration

type StatisticConfig

type StatisticConfig struct {
	Metrics *DatabaseAccess `yaml:"metrics"`
}

StatisticConfig statistics configuration

type StoreJWTHandler

type StoreJWTHandler struct {
}

StoreJWTHandler store session in a database store

func (*StoreJWTHandler) InvalidateUUID

func (st *StoreJWTHandler) InvalidateUUID(uuid string, elapsed time.Time) bool

InvalidateUUID invalidate UUID entry and given elapsed time

func (*StoreJWTHandler) Range

func (st *StoreJWTHandler) Range(f func(uuid, value any) bool) error

Range go through all session entries

func (*StoreJWTHandler) Store

func (st *StoreJWTHandler) Store(principal auth.PrincipalInterface, user, pass string) (err error)

Store store entry for given input

func (*StoreJWTHandler) UUIDInfo

func (st *StoreJWTHandler) UUIDInfo(uuid string) (*auth.SessionInfo, error)

UUIDInfo get UUID info User information

func (*StoreJWTHandler) ValidateUUID

func (st *StoreJWTHandler) ValidateUUID(claims *auth.JWTClaims) (auth.PrincipalInterface, bool)

ValidateUUID validate JWT claims are in UUID session list

type TaskConfig

type TaskConfig struct {
	Role      string    `yaml:"role,omitempty"`
	UseRole   bool      `yaml:"use_role,omitempty"`
	Directory string    `yaml:"directory,omitempty"`
	Database  *Database `yaml:"database,omitempty"`
}

TaskConfig job store

Directories

Path Synopsis
Code generated by ogen, DO NOT EDIT.
Code generated by ogen, DO NOT EDIT.
cmd
cluapi command
audit command
auth command
extend command
storeAudit command
validator command

Jump to

Keyboard shortcuts

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