Add Change Password API

Author: gmitch215

src/main/kotlin/io/codemc/api/jenkins/jenkins.kt

@@ -6,34 +6,59 @@ import com.cdancy.jenkins.rest.JenkinsClient
 import io.codemc.api.*
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
-import kotlinx.coroutines.withContext
 import org.jetbrains.annotations.VisibleForTesting
 import java.net.http.HttpRequest
 
+/**
+ * The [JenkinsConfig] instance.
+ */
 var jenkinsConfig: JenkinsConfig = JenkinsConfig("", "", "")
     set(value) {
         field = value
 
         val client0 = JenkinsClient.builder()
             .endPoint(value.url)
 
-        if (value.username.isNotEmpty() && value.password.isNotEmpty())
-            client0.credentials("${value.username}:${value.password}")
+        if (value.username.isNotEmpty() && value.token.isNotEmpty())
+            client0.credentials("${value.username}:${value.token}")
 
         client = client0.build()
     }
 
 private lateinit var client: JenkinsClient
 
+/**
+ * The Jenkins configuration.
+ * @param url The URL to the Jenkins Instance.
+ * @param username The Jenkins username.
+ * @param token The Jenkins API token.
+ */
 data class JenkinsConfig(
     val url: String,
     val username: String,
-    val password: String
+    val token: String
 )
 
+/**
+ * Pings the Jenkins server.
+ * @return `true` if the server is reachable, `false` otherwise.
+ */
 fun ping(): Boolean =
     client.api().systemApi().systemInfo().jenkinsVersion() != null
 
+// Credentials API Documentation:
+// https://github.com/jenkinsci/credentials-plugin/blob/master/docs/user.adoc
+
+/**
+ * The Jenkins Credentials ID for the Nexus Credentials.
+ */
+const val NEXUS_CREDENTIALS_ID = "nexus-repository"
+
+/**
+ * The Jenkins Credentials Description for the Nexus Credentials.
+ */
+const val NEXUS_CREDENTIALS_DESCRIPTION = "Your Nexus Login Details"
+
 internal suspend fun createCredentials(username: String, password: String): Boolean {
     // Create Credentials Domain
     val domainConfig = RESOURCE_CACHE[CREDENTIALS_DOMAIN] ?: return false
@@ -48,6 +73,8 @@ internal suspend fun createCredentials(username: String, password: String): Bool
 
     // Create Credentials Store
     val storeConfig = (RESOURCE_CACHE[CREDENTIALS] ?: return false)
+        .replace("{ID}", NEXUS_CREDENTIALS_ID)
+        .replace("{DESCRIPTION}", NEXUS_CREDENTIALS_DESCRIPTION)
         .replace("{USERNAME}", username.lowercase())
         .replace("{PASSWORD}", password)
 
@@ -61,6 +88,35 @@ internal suspend fun createCredentials(username: String, password: String): Bool
     return store.statusCode() == 200
 }
 
+/**
+ * Changes the Jenkins password for a user.
+ * @param username The username of the user.
+ * @param newPassword The new password.
+ * @return `true` if the password was changed, `false` otherwise.
+ */
+suspend fun changeJenkinsPassword(username: String, newPassword: String): Boolean {
+    val config = (RESOURCE_CACHE[CREDENTIALS] ?: return false)
+        .replace("{ID}", NEXUS_CREDENTIALS_ID)
+        .replace("{DESCRIPTION}", NEXUS_CREDENTIALS_DESCRIPTION)
+        .replace("{USERNAME}", username.lowercase())
+        .replace("{PASSWORD}", newPassword)
+
+    val res = req("${jenkinsConfig.url}/job/$username/credentials/store/folder/domain/Services/credential/$NEXUS_CREDENTIALS_ID/config.xml") {
+        POST(HttpRequest.BodyPublishers.ofString(config))
+
+        header("Authorization", "Basic ${client.authValue()}")
+        header("Content-Type", "application/xml")
+    }
+
+    return res.statusCode() == 200
+}
+
+/**
+ * Creates a Jenkins user.
+ * @param username The username of the user.
+ * @param password The password of the user.
+ * @return `true` if the user was created, `false` otherwise.
+ */
 fun createJenkinsUser(username: String, password: String): Boolean = runBlocking(Dispatchers.IO) {
     val config0 = RESOURCE_CACHE[USER_CONFIG] ?: return@runBlocking false
 
@@ -76,14 +132,31 @@ fun createJenkinsUser(username: String, password: String): Boolean = runBlocking
     return@runBlocking createCredentials(username, password)
 }
 
+/**
+ * Gets a Jenkins user's configuration.
+ * @param username The username of the user.
+ * @return The user's configuration in XML format.
+ */
 fun getJenkinsUser(username: String): String {
     val user = client.api().jobsApi().config("/", username)
     return user ?: ""
 }
 
+/**
+ * Gets all Jenkins users.
+ * @return A list of all Jenkins users mapped by their username.
+ */
 fun getAllJenkinsUsers(): List<String>
     = client.api().jobsApi().jobList("/").jobs().map { it.name() }
 
+/**
+ * Creates a Jenkins job.
+ * @param username The username of the user to create the job at.
+ * @param jobName The name of the job.
+ * @param repoLink The Git URL to the repository.
+ * @param isFreestyle `true` if the job is a freestyle job, `false` otherwise. A freestyle job is defined as a job that isn't built with Maven.
+ * @param config A function to modify the XML configuration of the job.
+ */
 @JvmOverloads
 fun createJenkinsJob(
     username: String,
@@ -110,11 +183,23 @@ internal fun getJenkinsJob(username: String, jobName: String): String {
     return job ?: ""
 }
 
+/**
+ * Gets the information of a Jenkins job.
+ * @param username The username of the user.
+ * @param jobName The name of the job.
+ * @return The job information, or `null` if the job doesn't exist.
+ */
 fun getJobInfo(username: String, jobName: String): JenkinsJob? {
     val job = client.api().jobsApi().jobInfo("/", "$username/job/$jobName")
     return if (job == null) null else JenkinsJob(job)
 }
 
+/**
+ * Triggers a build for a Jenkins job.
+ * @param username The username of the user.
+ * @param jobName The name of the job.
+ * @return `true` if the build was triggered, `false` otherwise.
+ */
 fun triggerBuild(username: String, jobName: String): Boolean {
     val status = client.api().jobsApi().build("/", "$username/job/$jobName")
     if (status.errors().isNotEmpty()) {
@@ -131,6 +216,11 @@ internal fun isBuilding(username: String, jobName: String): Boolean {
     return (job.color() ?: "").contains("anime") || job.inQueue() || (job.lastBuild()?.building() ?: false)
 }
 
+/**
+ * Deletes a Jenkins user.
+ * @param username The username of the user.
+ * @return `true` if the user was deleted, `false` otherwise.
+ */
 fun deleteUser(username: String): Boolean {
     val status = client.api().jobsApi().delete("/", username)
 
@@ -140,6 +230,11 @@ fun deleteUser(username: String): Boolean {
     return status.value()
 }
 
+/**
+ * Deletes a Jenkins job.
+ * @param username The username of the user.
+ * @param jobName The name of the job.
+ */
 fun deleteJob(username: String, jobName: String): Boolean {
     val status = client.api().jobsApi().delete("/", "$username/job/$jobName")
 
@@ -154,6 +249,9 @@ private val nonFreestyles = listOf(
     "dependency-reduced-pom.xml"
 )
 
-suspend fun isFreestyle(url: String): Boolean = withContext(Dispatchers.IO) {
-    !filesExists(url, nonFreestyles)
-}
+/**
+ * Checks if a Git repository is a freestyle project.
+ * @param url The URL to the Git repository.
+ * @return `true` if the project is a freestyle project, `false` otherwise.
+ */
+suspend fun isFreestyle(url: String): Boolean = !filesExists(url, nonFreestyles)

src/main/kotlin/io/codemc/api/nexus/nexus.kt

@@ -14,34 +14,68 @@ import java.util.*
 
 // Schema
 
+/**
+ * The Nexus configuration.
+ * @param url The URL to the Nexus Instance.
+ * @param username The username of the admin user.
+ * @parma password The password of the admin user.
+ */
 data class NexusConfig(
     val url: String,
     val username: String,
     val password: String
 ) {
+    /**
+     * The Base64-Encoded value of `$username:$password`
+     */
     private val token: String
         get() = Base64.getEncoder().encodeToString("$username:$password".toByteArray())
 
+    /**
+     * The authorization header based on the [username] and [password].
+     */
     val authorization
         get() = "Basic $token"
 }
 
 // Fields
 
+/**
+ * The [NexusConfig] instance.
+ */
 lateinit var nexusConfig: NexusConfig
 
 // Implementation
 
-private suspend fun nexus(url: String, request: HttpRequest.Builder.() -> Unit = { GET() }) = req(url) {
+/**
+ * Sends an HTTP request using the [NexusConfig.authorization] header.
+ * @param url The URL to send the request to.
+ * @param request The builder modifier on the HTTP Request.
+ * @return An HTTP Response.
+ * @see [req]
+ */
+suspend fun nexus(url: String, request: HttpRequest.Builder.() -> Unit = { GET() }) = req(url) {
     header("Authorization", nexusConfig.authorization)
     request(this)
 }
 
+/**
+ * Pings the Nexus Instance.
+ * @return `true` if currently available, `false` otherwise
+ */
 suspend fun ping(): Boolean {
     val text = nexus("$API_URL/status")
     return text.statusCode() == 200
 }
 
+/**
+ * Creates a Nexus User with the necessary data.
+ *
+ * This creates the user account, role, and repository with necessary credentials.
+ * @param name The name of the user
+ * @param password The password for the user
+ * @return `true` if successfully created, `false` otherwise.
+ */
 @OptIn(ExperimentalSerializationApi::class)
 suspend fun createNexus(name: String, password: String) = withContext(Dispatchers.IO) {
     // Create User Repository
@@ -91,16 +125,38 @@ suspend fun createNexus(name: String, password: String) = withContext(Dispatcher
     return@withContext userRes.statusCode() == 200
 }
 
+/**
+ * Changes the password linked to the Nexus User.
+ * @param name The name of the user to change
+ * @param newPassword The new password for the user
+ * @return `true` if the change was successful, `false` otherwise
+ */
+suspend fun changeNexusPassword(name: String, newPassword: String) = withContext(Dispatchers.IO) {
+    val id = name.lowercase()
+    val res = nexus("$API_URL/security/users/$id/change-password") {
+        PUT(HttpRequest.BodyPublishers.ofString(newPassword))
+
+        header("Content-Type", "text/plain")
+    }
+
+    return@withContext res.statusCode() == 204
+}
+
+/**
+ * Deletes a Nexus user and its data, removing all artifacts from its repository.
+ * @param name The name of the user to delete.
+ * @return `true` if the deletion was successful, `false` otherwise
+ */
 suspend fun deleteNexus(name: String) = withContext(Dispatchers.IO) {
-    val repoName = name.lowercase()
+    val id = name.lowercase()
 
-    val repoRes = nexus("$API_URL/repositories/$repoName") { DELETE() }
+    val repoRes = nexus("$API_URL/repositories/$id") { DELETE() }
     if (repoRes.statusCode() != 204) return@withContext false
 
-    val roleRes = nexus("$API_URL/security/roles/$repoName") { DELETE() }
+    val roleRes = nexus("$API_URL/security/roles/$id") { DELETE() }
     if (roleRes.statusCode() != 204) return@withContext false
 
-    val userRes = nexus("$API_URL/security/users/$repoName") { DELETE() }
+    val userRes = nexus("$API_URL/security/users/$id") { DELETE() }
     return@withContext userRes.statusCode() == 204
 }
 
@@ -110,13 +166,23 @@ internal suspend fun getRepositories(): List<JsonObject> {
     return json.decodeFromString(text)
 }
 
+/**
+ * Gets a Nexus Repository by its case-sensitive name.
+ * @param name The name of the nexus repository
+ * @return The repository data in JSON format, or `null` if not found
+ */
 suspend fun getNexusRepository(name: String): JsonObject? {
     val res = nexus("$API_URL/repositories/$name")
     if (res.statusCode() == 404) return null
 
     return json.decodeFromString(res.body())
 }
 
+/**
+ * Gets a Nexus User by its case-sensitive name.
+ * @param name The name of the nexus user.
+ * @return The User data in JSON format, or `null` if not found
+ */
 suspend fun getNexusUser(name: String): JsonObject? {
     val res = nexus("$API_URL/security/users?userId=$name")
     if (res.statusCode() == 404) return null

src/main/resources/templates/jenkins/credentials.xml

@@ -1,6 +1,6 @@
 <com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>
-    <id>nexus-repository</id>
-    <description>Your Nexus Login Details</description>
+    <id>{ID}</id>
+    <description>{DESCRIPTION}</description>
     <username>{USERNAME}</username>
     <password>{PASSWORD}</password>
     <usernameSecret>true</usernameSecret>

src/test/kotlin/io/codemc/api/TestOverall.kt

@@ -23,7 +23,7 @@ class TestOverall {
             val jenkins = JenkinsConfig(
                 url = "http://localhost:8080",
                 username = "admin",
-                password = "00000000000000000000000000000000"
+                token = "00000000000000000000000000000000"
             )
 
             val nexus = NexusConfig(

src/test/kotlin/io/codemc/api/jenkins/TestJenkins.kt

@@ -14,7 +14,7 @@ class TestJenkins {
             jenkinsConfig = JenkinsConfig(
                 url = "http://localhost:8080",
                 username = "admin",
-                password = "00000000000000000000000000000000"
+                token = "00000000000000000000000000000000"
             )
         }
 
@@ -119,4 +119,20 @@ class TestJenkins {
         assertFalse(isFreestyle(u4))
     }
 
+    @Test
+    fun testChangePassword() = runBlocking(Dispatchers.IO) {
+        val name = "OldUser788"
+
+        val p1 = "OldPassword123"
+        assertTrue(createJenkinsUser(name, p1))
+        assertTrue(getJenkinsUser(name).isNotEmpty())
+
+        val p2 = "NewPassword456"
+        assertTrue(changeJenkinsPassword(name, p2))
+        assertTrue(getJenkinsUser(name).isNotEmpty())
+
+        assertTrue(deleteUser(name))
+        assertTrue(getJenkinsUser(name).isEmpty())
+    }
+
 }