Add support for FGA endpoints (#244)

* Add module with support for FGA endpoints

* Add stub response method with scenario support

* Add support for retries on FGA endpoints

* Add FgaApi tests

* Remove log

* Update delete resource test

* Fix linter errors

* Add request options to Query to support warrant tokens

* Add tests for request options

Author: stanleyphu

src/main/kotlin/com/workos/WorkOS.kt

@@ -16,6 +16,7 @@ import com.workos.common.http.GenericErrorResponse
 import com.workos.common.http.RequestConfig
 import com.workos.common.http.UnprocessableEntityExceptionResponse
 import com.workos.directorysync.DirectorySyncApi
+import com.workos.fga.FgaApi
 import com.workos.mfa.MfaApi
 import com.workos.organizations.OrganizationsApi
 import com.workos.passwordless.PasswordlessApi
@@ -24,8 +25,18 @@ import com.workos.sso.SsoApi
 import com.workos.usermanagement.UserManagementApi
 import com.workos.webhooks.WebhooksApi
 import org.apache.http.client.utils.URIBuilder
+import java.io.IOException
 import java.lang.IllegalArgumentException
+import java.net.ConnectException
+import java.net.SocketTimeoutException
 import java.util.Properties
+import kotlin.random.Random
+import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
+
+@OptIn(ExperimentalTime::class)
+val MINIMUM_SLEEP_TIME = Duration.milliseconds(500)
+val BACKOFF_MULTIPLER = 1.5
 
 /**
  * Global configuration class for interacting with the WorkOS API.
@@ -108,6 +119,12 @@ class WorkOS(
   @JvmField
   val webhooks = WebhooksApi()
 
+  /**
+   * Module for interacting with the FGA API.
+   */
+  @JvmField
+  val fga = FgaApi(this)
+
   /**
    * The base URL for making API requests to.
    */
@@ -234,6 +251,10 @@ class WorkOS(
   }
 
   private fun sendRequest(request: Request): String {
+    if (request.url.path.contains("fga")) {
+      return sendRequestWithRetry(request)
+    }
+
     val (_, response) = request.responseString()
 
     var payload = String(response.data)
@@ -249,6 +270,82 @@ class WorkOS(
     return payload
   }
 
+  @OptIn(ExperimentalTime::class)
+  private fun sendRequestWithRetry(request: Request): String {
+    var requestException: Exception? = null
+    var response: Response? = null
+    var retryAttempts = 0
+
+    while (true) {
+      requestException = null
+
+      try {
+        val (_, res) = request.responseString()
+        response = res
+      } catch (e: IOException) {
+        requestException = e
+      } catch (e: InterruptedException) {
+        requestException = e
+      }
+
+      if (!shouldRetryRequest(response, retryAttempts, requestException)) {
+        break
+      }
+
+      retryAttempts += 1
+
+      try {
+        Thread.sleep(getSleepTime(retryAttempts).inWholeMilliseconds)
+      } catch (e: InterruptedException) {
+        Thread.currentThread().interrupt()
+      }
+    }
+
+    if (requestException != null) {
+      throw requestException
+    }
+
+    var payload = if (response != null) String(response.data) else ""
+
+    if (payload.isEmpty()) {
+      payload = "{}"
+    }
+
+    if (response != null && response.statusCode >= 400) {
+      handleResponseError(response, payload)
+    }
+
+    return payload
+  }
+
+  private fun shouldRetryRequest(response: Response?, retryAttempts: Int, requestException: Exception?): Boolean {
+    if (retryAttempts >= 3) {
+      return false
+    }
+
+    if ((requestException != null) && (requestException.cause != null) && (requestException.cause is ConnectException || requestException.cause is SocketTimeoutException)) {
+      return true
+    }
+
+    if ((requestException != null) && (requestException.cause != null) && (requestException.cause is IOException)) {
+      return true
+    }
+
+    if (response != null && response.statusCode >= 500) {
+      return true
+    }
+
+    return false
+  }
+
+  @OptIn(ExperimentalTime::class)
+  private fun getSleepTime(retryAttempt: Int): Duration {
+    var sleepTime: Duration = Duration.nanoseconds(MINIMUM_SLEEP_TIME.inWholeNanoseconds * Math.pow(BACKOFF_MULTIPLER, (retryAttempt + 1).toDouble()))
+    val jitter = Random.nextDouble(0.5, 1.5)
+    sleepTime = Duration.nanoseconds(sleepTime.inWholeNanoseconds * jitter)
+    return sleepTime
+  }
+
   private fun <Res : Any> sendRequest(request: Request, responseType: Class<Res>): Res {
     val response = sendRequest(request)
     return mapper.readValue(response, responseType)

src/main/kotlin/com/workos/fga/FgaApi.kt

@@ -0,0 +1,128 @@
+package com.workos.fga
+
+import com.workos.WorkOS
+import com.workos.common.http.RequestConfig
+import com.workos.fga.models.CheckResponse
+import com.workos.fga.models.QueryResponse
+import com.workos.fga.models.Resource
+import com.workos.fga.models.Resources
+import com.workos.fga.models.Warrants
+import com.workos.fga.models.WriteWarrantResponse
+import com.workos.fga.types.CheckBatchOptions
+import com.workos.fga.types.CheckOptions
+import com.workos.fga.types.CheckRequestOptions
+import com.workos.fga.types.CreateResourceOptions
+import com.workos.fga.types.ListResourcesOptions
+import com.workos.fga.types.ListWarrantsOptions
+import com.workos.fga.types.QueryOptions
+import com.workos.fga.types.QueryRequestOptions
+import com.workos.fga.types.UpdateResourceOptions
+import com.workos.fga.types.WriteWarrantOptions
+
+class FgaApi(private val workos: WorkOS) {
+  /** Get an existing resource. */
+  fun getResource(resourceType: String, resourceId: String): Resource {
+    return workos.get("/fga/v1/resources/$resourceType/$resourceId", Resource::class.java)
+  }
+
+  /** Get a list of all the existing resources matching the criteria specified */
+  fun listResources(options: ListResourcesOptions? = null): Resources {
+    val params: Map<String, String> =
+      RequestConfig.toMap(options ?: ListResourcesOptions()) as Map<String, String>
+
+    return workos.get(
+      "/fga/v1/resources",
+      Resources::class.java,
+      RequestConfig.builder().params(params).build()
+    )
+  }
+
+  /** Create a new resource in the current environment. */
+  fun createResource(options: CreateResourceOptions): Resource {
+    return workos.post(
+      "/fga/v1/resources",
+      Resource::class.java,
+      RequestConfig.builder().data(options).build()
+    )
+  }
+
+  /** Update an existing resource. */
+  fun updateResource(resourceType: String, resourceId: String, options: UpdateResourceOptions): Resource {
+    return workos.put(
+      "/fga/v1/resources/$resourceType/$resourceId",
+      Resource::class.java,
+      RequestConfig.builder().data(options).build()
+    )
+  }
+
+  /** Delete a resource in the current environment. */
+  fun deleteResource(resourceType: String, resourceId: String) {
+    workos.delete("/fga/v1/resources/$resourceType/$resourceId")
+  }
+
+  /** Get a list of all existing warrants matching the criteria specified */
+  fun listWarrants(options: ListWarrantsOptions? = null): Warrants {
+    val params: Map<String, String> =
+      RequestConfig.toMap(options ?: ListWarrantsOptions()) as Map<String, String>
+
+    return workos.get(
+      "/fga/v1/warrants",
+      Warrants::class.java,
+      RequestConfig.builder().params(params).build()
+    )
+  }
+
+  /** Perform a warrant write (create/delete) in the current environment */
+  fun writeWarrant(options: WriteWarrantOptions): WriteWarrantResponse {
+    return workos.post(
+      "/fga/v1/warrants",
+      WriteWarrantResponse::class.java,
+      RequestConfig.builder().data(options).build()
+    )
+  }
+
+  /** Performs multiple warrant writes in the current environment */
+  fun batchWriteWarrants(options: List<WriteWarrantOptions>): WriteWarrantResponse {
+    return workos.post(
+      "/fga/v1/warrants",
+      WriteWarrantResponse::class.java,
+      RequestConfig.builder().data(options).build()
+    )
+  }
+
+  /** Perform a warrant check in the current environment */
+  fun check(options: CheckOptions, requestOptions: CheckRequestOptions? = null): CheckResponse {
+    val config = RequestConfig.builder()
+      .data(options)
+
+    if (requestOptions != null) {
+      config.headers(mapOf("Warrant-Token" to requestOptions.warrantToken))
+    }
+
+    return workos.post("/fga/v1/check", CheckResponse::class.java, config.build())
+  }
+
+  /** Perform a batch warrant check in the current environment */
+  fun checkBatch(options: CheckBatchOptions, requestOptions: CheckRequestOptions? = null): Array<CheckResponse> {
+    val config = RequestConfig.builder()
+      .data(options)
+
+    if (requestOptions != null) {
+      config.headers(mapOf("Warrant-Token" to requestOptions.warrantToken))
+    }
+
+    return workos.post("/fga/v1/check", Array<CheckResponse>::class.java, config.build())
+  }
+
+  /** Perform a query in the current environment */
+  fun query(options: QueryOptions, requestOptions: QueryRequestOptions? = null): QueryResponse {
+    val config = RequestConfig.builder()
+      .data(options)
+
+    if (requestOptions != null) {
+      config.headers(mapOf("Warrant-Token" to requestOptions.warrantToken))
+    }
+
+    return workos.post("/fga/v1/query", QueryResponse::class.java, config.build())
+  }
+}

src/main/kotlin/com/workos/fga/builders/CheckBatchOptionsBuilder.kt

@@ -0,0 +1,27 @@
+package com.workos.fga.builders
+
+import com.workos.fga.types.CheckBatchOptions
+import com.workos.fga.types.WarrantCheckOptions
+
+class CheckBatchOptionsBuilder @JvmOverloads constructor(
+  private var checks: List<WarrantCheckOptions>,
+  private var debug: Boolean? = null,
+) {
+  fun checks(value: List<WarrantCheckOptions>) = apply { checks = value }
+
+  fun debug(value: Boolean) = apply { debug = value }
+
+  fun build(): CheckBatchOptions {
+    return CheckBatchOptions(
+      checks = this.checks,
+      debug = this.debug,
+    )
+  }
+
+  companion object {
+    @JvmStatic
+    fun create(checks: List<WarrantCheckOptions>, debug: Boolean? = null): CheckBatchOptionsBuilder {
+      return CheckBatchOptionsBuilder(checks, debug)
+    }
+  }
+}

src/main/kotlin/com/workos/fga/builders/CheckOptionsBuilder.kt

@@ -0,0 +1,38 @@
+package com.workos.fga.builders
+
+import com.workos.fga.types.CheckOptions
+import com.workos.fga.types.WarrantCheckOptions
+
+class CheckOptionsBuilder @JvmOverloads constructor(
+  private var op: String? = null,
+  private var checks: List<WarrantCheckOptions>,
+  private var debug: Boolean? = null,
+) {
+  constructor(checks: List<WarrantCheckOptions>, debug: Boolean? = null) : this(null, checks, debug)
+
+  fun op(value: String) = apply { op = value }
+
+  fun checks(value: List<WarrantCheckOptions>) = apply { checks = value }
+
+  fun debug(value: Boolean) = apply { debug = value }
+
+  fun build(): CheckOptions {
+    return CheckOptions(
+      op = this.op,
+      checks = this.checks,
+      debug = this.debug,
+    )
+  }
+
+  companion object {
+    @JvmStatic
+    fun create(op: String, checks: List<WarrantCheckOptions>, debug: Boolean? = null): CheckOptionsBuilder {
+      return CheckOptionsBuilder(op, checks, debug)
+    }
+
+    @JvmStatic
+    fun create(checks: List<WarrantCheckOptions>, debug: Boolean? = null): CheckOptionsBuilder {
+      return CheckOptionsBuilder("", checks, debug)
+    }
+  }
+}

src/main/kotlin/com/workos/fga/builders/CreateResourceOptionsBuilder.kt

@@ -0,0 +1,30 @@
+package com.workos.fga.builders
+
+import com.workos.fga.types.CreateResourceOptions
+
+class CreateResourceOptionsBuilder @JvmOverloads constructor(
+  private var resourceType: String,
+  private var resourceId: String? = null,
+  private var meta: Map<String, String>? = null,
+) {
+  fun resourceType(value: String) = apply { resourceType = value }
+
+  fun resourceId(value: String) = apply { resourceId = value }
+
+  fun meta(value: Map<String, String>) = apply { meta = value }
+
+  fun build(): CreateResourceOptions {
+    return CreateResourceOptions(
+      resourceType = this.resourceType,
+      resourceId = this.resourceId,
+      meta = this.meta,
+    )
+  }
+
+  companion object {
+    @JvmStatic
+    fun create(resourceType: String): CreateResourceOptionsBuilder {
+      return CreateResourceOptionsBuilder(resourceType)
+    }
+  }
+}