[apricot] Implement component configuration access in HTTP API

.github/workflows/control.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [macOS-latest, ubuntu-20.04]
-        go: [ '1.18.4' ]
+        go: [ '1.21.5' ]
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-go@v2

Makefile

@@ -250,16 +250,23 @@ tools/protoc:
 
 	@export GOBIN="$(ROOT_DIR)/tools" && cat common/tools/tools.go | grep _ | awk -F'"' '{print $$2}' | xargs -tI % go install -mod=readonly %
 
-docs: doc
+docs: docs/coconut docs/grpc docs/swaggo
 
-doc:
+docs/coconut:
 	@echo -e "generating coconut documentation  \033[1;33m==>\033[0m  \033[1;34m./coconut/doc\033[0m"
 	@cd coconut/doc && go run . && cd ../..
+
+docs/grpc:
 	@echo -e "generating gRPC API documentation  \033[1;33m==>\033[0m  \033[1;34m./docs\033[0m"
 	@cd apricot/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_apricot.md "apricot.proto"
 	@cd core/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_aliecs.md "o2control.proto"
 	@cd occ/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_occ.md "occ.proto"
 
+docs/swaggo:
+	@echo -e "generating REST API documentation  \033[1;33m==>\033[0m  \033[1;34m./apricot/docs\033[0m"
+	@tools/swag fmt -d apricot
+	@tools/swag init -o apricot/docs -d apricot/local,apricot,cmd/o2-apricot -g servicehttp.go
+
 help:
 	@echo "available make variables:"
 	@echo "  V                 - Build verbosity {0,1,2}."

apricot/cacheproxy/service.go

@@ -7,22 +7,22 @@ import (
 
 // Implements a cache proxy Service for the configuration system.
 // Only DetectorForHost/DetectorsForHosts are cached, all other calls are passed through.
-type Service struct{
-	base configuration.Service
+type Service struct {
+	base  configuration.Service
 	cache svcCache
 }
 
 type svcCache struct {
 	detectorsInventory map[string][]string
-	detectorForHost map[string]string
+	detectorForHost    map[string]string
 }
 
 func NewService(base configuration.Service) (*Service, error) {
 	svc := &Service{
 		base: base,
 		cache: svcCache{
 			detectorsInventory: make(map[string][]string),
-			detectorForHost: make(map[string]string),
+			detectorForHost:    make(map[string]string),
 		},
 	}
 
@@ -144,3 +144,7 @@ func (s Service) GetEndpointsForCRUCard(hostname, cardSerial string) (string, er
 func (s Service) RawGetRecursive(path string) (string, error) {
 	return s.base.RawGetRecursive(path)
 }
+
+func (s Service) InvalidateComponentTemplateCache() {
+	s.base.InvalidateComponentTemplateCache()
+}

apricot/docs/apricot_http_service.md

@@ -0,0 +1,43 @@
+## apricot HTTP service
+
+Web server component that implements the REST Configuration Endpoint (Apricot RCE). 
+
+It serves JSON and/or plain text structures in order to make essential cluster information and component configuration available to scripts and other consumers for which the gRPC interface is impractical.
+
+It is strictly **read-only** and only ever responds to `GET` (except for the special purpose `POST` call `/components/_invalidate_cache`, called only by Consul).
+
+### Configuration
+
+To use this feature, the `o2-apricot` running machine has to communicate with Consul via the `--backendUri` option (see [here](apricot.md)).
+
+### Usage and options
+
+The default port is `32188`.
+
+To retrieve the information needed regarding FLPs, use the following urls in a web browser or with `curl` or `wget`.
+
+To retrieve as plain text:
+* `http://<apricot-server>/inventory/flps` or `http://<apricot-server>/inventory/flps/text`
+* `http://<apricot-server>/inventory/detectors/<detector>/flps` or `http://<apricot-server>/inventory/detectors/<detector>/flps/text`
+
+To retrieve as JSON:
+* `http://<apricot-server>/inventory/flps/json`
+* `http://<apricot-server>/inventory/detectors/<detector>/flps/json`
+
+To retrieve a component configuration payload, use the following urls in a web browser or with `curl` or `wget`.
+
+* `http://<apricot-server>/components/<component>/<runtype>/<rolename>/<entry>?process=true` - with template processing
+* `http://<apricot-server>/components/<component>/<runtype>/<rolename>/<entry>?process=false` - without template processing, returns the entry verbatim
+
+The full API documentation is available at `http://<apricot-server>/docs/` wherever your Apricot instance is running. This documentation interface also allows to perform API calls directly from the browser.
+Besides configuration retrieval, the API also includes calls for browsing the configuration tree and resolving payload paths to actual entries according to the `ANY/any` mechanism. 
+
+### Examples
+
+* With `curl`: `curl http://localhost:32188/inventory/flps`
+* With `wget`: `wget http://localhost:32188/inventory/detectors/TST/flps/json -O ~/downloads/test`
+
+Getting a template-processed configuration payload for a component (entry `tpc-full-qcmn` for component `qc`, with `list_of_detectors` and `run_type` passed as template variables):
+
+* In a browser: `http://localhost:32188/components/qc/ANY/any/tpc-full-qcmn?process=true&list_of_detectors=tpc,its&run_type=PHYSICS`
+* With `curl`: `curl http://127.0.0.1:32188/components/qc/ANY/any/tpc-full-qcmn\?process\=true\&list_of_detectors\=tpc,its\&run_type\=PHYSICS`