feat: Add a URL template utility.

Author: bgrozev

src/main/kotlin/org/jitsi/utils/TemplatedUrl.kt

@@ -0,0 +1,50 @@
+/*
+ * Copyright @ 2025 - present 8x8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jitsi.utils
+
+import java.net.URI
+
+class TemplatedUrl(
+    private val template: String,
+    private val map: MutableMap<String, String> = mutableMapOf(),
+    private val requiredKeys: Set<String> = emptySet(),
+) {
+
+    /** Saves the given key:value pair in the map. */
+    fun set(key: String, value: String) {
+        map[key] = value
+    }
+
+    /** Resolve the template with the current map. */
+    fun resolve() = doResolve(map)
+
+    /** Resolve the template with the current map and a new key:value pair (does not save the new pair). */
+    fun resolve(key: String, value: String) = resolve(mapOf(key to value))
+
+    /** Resolve the template with the current map and a new map pair (does not save the new map). */
+    fun resolve(newMap: Map<String, String>) = doResolve(map + newMap)
+
+    private fun doResolve(map: Map<String, String>): URI {
+        if (!requiredKeys.all { it in map }) {
+            throw IllegalArgumentException("Missing required keys: ${requiredKeys - map.keys}")
+        }
+        var resolvedUrl = template
+        for ((key, value) in map) {
+            resolvedUrl = resolvedUrl.replace("{{$key}}", value)
+        }
+        return URI(resolvedUrl)
+    }
+}

src/test/kotlin/org/jitsi/utils/TemplatedUrlTest.kt

@@ -0,0 +1,95 @@
+/*
+ * Copyright @ 2025 - present 8x8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jitsi.utils
+
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.core.spec.style.ShouldSpec
+import io.kotest.matchers.shouldBe
+import java.net.URI
+import java.net.URISyntaxException
+
+class TemplatedUrlTest : ShouldSpec({
+    context("TemplatedUrl") {
+        should("resolve a simple template") {
+            val template = "https://example.com/{{path}}"
+            val templatedUrl = TemplatedUrl(template)
+            templatedUrl.set("path", "test")
+
+            templatedUrl.resolve() shouldBe URI("https://example.com/test")
+        }
+
+        should("resolve a template with multiple keys") {
+            val template = "wss://{{host}}/{{path}}?param={{param}}"
+            val templatedUrl = TemplatedUrl(template)
+            templatedUrl.set("host", "example.com")
+            templatedUrl.set("path", "api/resource")
+            templatedUrl.set("param", "value")
+
+            templatedUrl.resolve() shouldBe URI("wss://example.com/api/resource?param=value")
+        }
+
+        should("resolve a template with multiple keys when they are not set()") {
+            val template = "wss://{{host}}/{{path}}?param={{param}}"
+            val templatedUrl = TemplatedUrl(template)
+            templatedUrl.set("host", "example.com")
+            templatedUrl.set("path", "api/resource")
+            templatedUrl.set("param", "value")
+
+            templatedUrl.resolve(
+                mapOf("host" to "example.com", "path" to "api/resource", "param" to "value")
+            ) shouldBe URI("wss://example.com/api/resource?param=value")
+        }
+
+        should("resolve with a new key-value pair without saving it") {
+            val template = "https://example.com/{{path}}?param={{param}}"
+            val templatedUrl = TemplatedUrl(template)
+            templatedUrl.set("path", "api")
+
+            // Resolve with temporary param value
+            templatedUrl.resolve("param", "temp") shouldBe URI("https://example.com/api?param=temp")
+
+            // Original template should not have the param saved
+            templatedUrl.set("param", "permanent")
+            templatedUrl.resolve() shouldBe URI("https://example.com/api?param=permanent")
+        }
+
+        should("throw an exception when not all requiredKeys are set") {
+            val template = "https://example.com/{{path}}?param={{param}}"
+            val templatedUrl = TemplatedUrl(template, requiredKeys = setOf("param"))
+            templatedUrl.set("path", "api")
+
+            shouldThrow<IllegalArgumentException> {
+                templatedUrl.resolve()
+            }
+        }
+        should("throw an exception when the URI is invalid") {
+            val templatedUrl = TemplatedUrl("https://example.com/{{}}")
+
+            shouldThrow<URISyntaxException> {
+                templatedUrl.resolve()
+            }
+        }
+
+        should("handle keys that appear multiple times") {
+            val template = "https://{{host}}/{{path}}/{{path}}"
+            val templatedUrl = TemplatedUrl(template)
+            templatedUrl.set("host", "example.com")
+            templatedUrl.set("path", "resource")
+
+            templatedUrl.resolve() shouldBe URI("https://example.com/resource/resource")
+        }
+    }
+})