improve code and management interface (actuators)

- move actuator related stuff in its own package
- use builtin actuators when possible (remove cache evict)
- add /about endpoint to mirror actuator's /info
- make the management interface mostly made to run on another port (in production at least)

Author: derlin

README.md

@@ -23,8 +23,9 @@ This repository is the cornerstone of BBData. It contains:
   * [Async](#async)
 - [Permission system](#permission-system)
 - [Actuators](#actuators)
-  * [Customizing the `/info` endpoint](#customizing-the-info-endpoint)
-  * [Hidden async task executor endpoint](#hidden-async-task-executor-endpoint)
+  * [Management interface](#management-interface)
+  * [Customizing the `/info` endpoint](#customizing-the-about-info-endpoint)
+  * [Task executor monitoring](#task-executor-monitoring)
   * [Changing exposed actuators](#changing-exposed-actuators)
 
 ## Development setup
@@ -115,13 +116,16 @@ spring.datasource.url = jdbc:mysql://HOST:PORT/bbdata2?autoReconnect=true&useUni
 spring.datasource.username=bbdata-admin
 spring.datasource.password=PASSWORD
 
-## Cassandra properties
+## Cassandra properties
 spring.data.cassandra.contact-points=IP_1,IP_2,IP_X
 spring.data.cassandra.consistency-level=quorum
 
 ## Kafka properties
 spring.kafka.producer.bootstrap-servers=HOST:PORT
 spring.kafka.template.default-topic=bbdata2-augmented
+
+## Secured actuators endpoints (ensure the port is not available to the outside world)
+management.server.port=SECURED-PORT
 ```
 
 ### Executing the jar
@@ -179,12 +183,8 @@ By default, the cache logger is set to `INFO`. Feel free to change it using:
 logging.level.org.springframework.cache=TRACE
 ```
 
-When caching is enabled, a hidden endpoint is available in order to clear all cache entries: `GET /cache-evict`. 
-In order to avoid having folks discover this endpoint and play with it, you can configure a secret key to use via the property:
-```properties
-cache.evict.secret-key=XXX
-```
-If this property is defined, you will have to use `GET /cache-evict?key=XXX` for the eviction to be performed.
+When caching is enabled, you can use the `DELETE /caches` actuator endpoint to clear all cache entries.
+It is enabled by default (`management.endpoints.web.exposure.include=caches, ...`).
 
 
 **IMPORTANT**: in case you deploy the input api and the output api separately (using profiles), 
@@ -232,9 +232,26 @@ This is the equivalent of `SUDO`: any admin of this group has read/write access
 
 ## Actuators
 
-### Customizing the `/info` endpoint
+### Management interface
+
+Actuators are a way to monitor the API. They can leak sensitive information, so the management interface should
+run on another port as the API, which only administrators have access to.
+
+By default, the actuators will run on the same port (easier for debug, as they will show in openapi), but this is
+definitely unsecure in production. Hence, ensure you select another port for the management interface by setting either:
+```properties
+# 8111 should be protected by firewall or not exposed to the outside
+management.server.port=8111
+```
+or by disabling unsecure actuators, e.g.:
+```properties
+management.endpoints.web.exposure.include=info
+```
+
+### Customizing the `/about` (`/info`) endpoint
 
-The info endpoint can be customized using properties. 
+The actuator endpoint `/info` is mirrored in the public `/about` endpoint.
+What is actually displayed can be customized using properties.
 
 By default, SpringBoot actuator will add the to the JSON response any property with the prefix `info`.
 For example, to configure the `instance-name`, define the following in your `application.properties`:
@@ -257,17 +274,20 @@ dynamic.info.<JSON-KEY-NAME-WITHOUT-DOTS>=<ANOTHER PROPERTY>
 
 To hide a dynamic property that is displayed, simply redefine it with an empty value, e.g. `dynamic.info.cache-type=`.
 
-### Hidden async task executor endpoint
-
-By default, and if `sync.enabled=true`, there is a hidden `/tasks` endpoint that returns statistics about the task executor
-(core size, active threads) and the tasks. I is though hidden from the swagger documentation.
+### task executor monitoring
 
-To disable this endpoint, see changing exposed actuators.
+By default, and if `sync.enabled=true`, there is a custom `/tasks` actuator that returns statistics about the task executor
+(core size, active threads) and the tasks. To disable this endpoint, change exposed actuators (`id=tasks`).
 
 ### Changing exposed actuators
 
-By default, the exposed actuators are:
+[Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready)
+
+By default, the exposed actuators are defined in `application.properties`, using the key
+`management.endpoints.web.exposure.include=`. Feel free to change this list as you see fit.
+
+To **turn off** all endpoints, simply add:
 ```properties
-management.endpoints.web.exposure.include=info, health, metrics, tasks
-```
-Feel free to change this list as you see fit, but remember that they are all public !
+management.port=
+management.endpoints.web.exposure.include=none
+```

src/main/kotlin/ch/derlin/bbdata/AboutController.kt

@@ -0,0 +1,32 @@
+package ch.derlin.bbdata
+
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.tags.Tag
+import org.springframework.boot.actuate.autoconfigure.endpoint.condition.ConditionalOnAvailableEndpoint
+import org.springframework.boot.actuate.info.InfoEndpoint
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.RestController
+
+
+/**
+ * date: 29.12.19
+ * @author Lucy Linder <lucy.derlin@gmail.com>
+ */
+
+
+@RestController
+@Tag(name = "About", description = "API Status")
+// the following annotation is for tests to run. I dunno why, but in tests InfoEndpoint is not available,
+// but in normal mode the /about endpoint is registered even if management.endpoints.web.exposure.include doesn't
+// include info ...
+@ConditionalOnAvailableEndpoint(endpoint = InfoEndpoint::class)
+class AboutController(private val infoEndpoint: InfoEndpoint) {
+    /**
+     * Since the management interface (actuator) usually runs on another port,
+     * add the /about endpoint to the API using a "proxy": just call the actuator and return the result.
+     * This means everything configured in CustomInfoContributor will still hold.
+     */
+    @GetMapping("/about")
+    @Operation(description = "Get generic information about the running API instance.")
+    fun getInfo(): Map<String, Any> = infoEndpoint.info()
+}

src/main/kotlin/ch/derlin/bbdata/AsyncConfig.kt

@@ -1,17 +1,12 @@
 package ch.derlin.bbdata
 
-import io.swagger.v3.oas.annotations.Hidden
-import io.swagger.v3.oas.annotations.Operation
 import org.slf4j.Logger
 import org.slf4j.LoggerFactory
 import org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler
 import org.springframework.beans.factory.annotation.Value
-import org.springframework.boot.actuate.endpoint.annotation.ReadOperation
-import org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
 import org.springframework.boot.task.TaskExecutorCustomizer
 import org.springframework.context.annotation.Configuration
-import org.springframework.core.task.TaskExecutor
 import org.springframework.scheduling.annotation.AsyncConfigurer
 import org.springframework.scheduling.annotation.EnableAsync
 import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor
@@ -34,8 +29,16 @@ import java.util.concurrent.ThreadPoolExecutor
  */
 
 
+@kotlin.annotation.Retention(AnnotationRetention.RUNTIME)
+@kotlin.annotation.Target(AnnotationTarget.TYPE, AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
+@ConditionalOnProperty(AsyncProperties.ENABLED, havingValue = "true", matchIfMissing = true)
+annotation class OnAsyncEnabled
+
+
 @Component
 class AsyncExecutorCustomizer : TaskExecutorCustomizer {
+    /** Create a custom taskExecutor with CallerRuns policy */
+
     @Value("\${spring.task.execution.pool.queue-capacity}")
     val queueCapacity: Int = -1
     val logger: Logger = LoggerFactory.getLogger(AsyncExecutorCustomizer::class.java)
@@ -50,50 +53,29 @@ class AsyncExecutorCustomizer : TaskExecutorCustomizer {
     }
 }
 
-@ConditionalOnProperty(AsyncProperties.ENABLED, havingValue = "true", matchIfMissing = true)
+@OnAsyncEnabled
 @EnableAsync
 @Configuration
 class AsyncConfig : AsyncConfigurer {
+    /**
+     * Register a custom exception handler to ensure exceptions thrown asynchronously are still logged.
+     * Attention: this will be called only on async method with void return type !
+     */
+
     override fun getAsyncUncaughtExceptionHandler(): AsyncUncaughtExceptionHandler? {
         return AsyncExceptionHandler()
     }
 }
 
 class AsyncExceptionHandler : AsyncUncaughtExceptionHandler {
+    /**
+     * Actual logger used for asynchronous uncaught exceptions (methods with void return type only)
+     */
 
     val logger: Logger = LoggerFactory.getLogger(AsyncExceptionHandler::class.java)
 
-    /**
-     * Ensure we get the exception logged.
-     * Attention: this will be called only on async method with void return type !
-     */
     override fun handleUncaughtException(throwable: Throwable, method: Method, vararg params: Any) {
         val niceParams = params.take(2).joinToString(",") { it.toString() }
         logger.error("in ${method.name} with ${params.size} params: $niceParams ...", throwable)
     }
-}
-
-@Component
-@ConditionalOnProperty(AsyncProperties.ENABLED, havingValue = "true", matchIfMissing = true)
-@WebEndpoint(id = "tasks")
-class AsyncMonitor(private val taskExecutor: TaskExecutor? = null) {
-    /** add an optional tasks actuator to monitor async executor (hidden) */
-
-    @ReadOperation
-    @Operation(description = "Actuator web endpoint 'tasks', monitor async tasks execution")
-    @Hidden
-    fun executorInfo(): Map<String, Any> {
-        // use linkedMap to preserve insertion order in output
-        val executorInfo = linkedMapOf<String, Any>()
-        val tasksInfo = linkedMapOf<String, Any>()
-        if (taskExecutor is ThreadPoolTaskExecutor)
-            taskExecutor.threadPoolExecutor.let {
-                executorInfo["pool-size"] = it.corePoolSize
-                executorInfo["active-count"] = it.activeCount
-                executorInfo["queue-size"] = it.queue.size
-                tasksInfo["task-count"] = it.taskCount
-                tasksInfo["completed-task-count"] = it.completedTaskCount
-            }
-        return linkedMapOf("executor" to executorInfo, "tasks" to tasksInfo)
-    }
 }

src/main/kotlin/ch/derlin/bbdata/CustomProperties.kt

@@ -46,16 +46,6 @@ class AsyncProperties {
     }
 }
 
-@Configuration
-@ConfigurationProperties(prefix = "cache.evict")
-class CacheEvictProperties {
-
-    /** Optional secret key to call cache evict: see CacheEvictController */
-    var secretKey: String = ""
-
-    fun matches(key: String?): Boolean = secretKey.isBlank() || key?.equals(secretKey) ?: false
-}
-
 @Configuration
 @ConfigurationProperties(prefix = "datetime")
 class DateTimeFormatProperties {

src/main/kotlin/ch/derlin/bbdata/actuators/AsyncMonitor.kt

@@ -0,0 +1,41 @@
+package ch.derlin.bbdata.actuators
+
+import ch.derlin.bbdata.OnAsyncEnabled
+import io.swagger.v3.oas.annotations.Hidden
+import io.swagger.v3.oas.annotations.Operation
+import org.springframework.boot.actuate.endpoint.annotation.ReadOperation
+import org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint
+import org.springframework.core.task.TaskExecutor
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor
+import org.springframework.stereotype.Component
+
+/**
+ * date: 21.09.20
+ * @author Lucy Linder <lucy.derlin@gmail.com>
+ */
+
+@Component
+@OnAsyncEnabled
+@WebEndpoint(id = "tasks")
+class AsyncMonitor(private val taskExecutor: TaskExecutor? = null) {
+    /** add an optional tasks actuator to monitor async executor (hidden) */
+
+    @ReadOperation
+    @Operation(description = "Actuator web endpoint 'tasks', monitor async tasks execution")
+    @Hidden
+    fun executorInfo(): Map<String, Any> {
+        // use linkedMap to preserve insertion order in output
+        val executorInfo = linkedMapOf<String, Any>()
+        val tasksInfo = linkedMapOf<String, Any>()
+        if (taskExecutor is ThreadPoolTaskExecutor)
+            taskExecutor.threadPoolExecutor.let {
+                executorInfo["pool-size"] = it.corePoolSize
+                executorInfo["active-count"] = it.activeCount
+                executorInfo["queue-size"] = it.queue.size
+                tasksInfo["task-count"] = it.taskCount
+                tasksInfo["completed-task-count"] = it.completedTaskCount
+            }
+        return linkedMapOf("executor" to executorInfo, "tasks" to tasksInfo)
+    }
+}
+

…derlin/bbdata/output/api/ActuatorInfo.kt …bdata/actuators/CustomInfoContributor.ktsrc/main/kotlin/ch/derlin/bbdata/output/api/ActuatorInfo.kt renamed to src/main/kotlin/ch/derlin/bbdata/actuators/CustomInfoContributor.kt src/main/kotlin/ch/derlin/bbdata/output/api/ActuatorInfo.kt renamed to src/main/kotlin/ch/derlin/bbdata/actuators/CustomInfoContributor.kt

@@ -1,4 +1,4 @@
-package ch.derlin.bbdata.output.api
+package ch.derlin.bbdata.actuators
 
 import org.joda.time.DateTime
 import org.springframework.beans.factory.annotation.Autowired
@@ -9,14 +9,16 @@ import org.springframework.core.env.Environment
 import org.springframework.stereotype.Component
 import javax.annotation.PostConstruct
 
-
 /**
- * date: 29.12.19
+ * date: 21.09.20
  * @author Lucy Linder <lucy.derlin@gmail.com>
  */
 @Component
 @ConfigurationProperties(prefix = "dynamic")
 class CustomInfoContributor : InfoContributor {
+    /**
+     * Customize the actuator endpoint /info with dynamic properties and server time
+     */
 
     // any field in the form dynamic.info.key=property
     // the property is the key of another property in the *.properties on the classpath