@ir-kit/kit 0.0.0-stage → 1.0.0

package/runtime/java/ApiClient.java

@@ -0,0 +1,109 @@
+package dev.irkit.runtime;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.function.UnaryOperator;
+
+public final class ApiClient {
+  public URI baseUri;
+  public final HttpClient httpClient;
+  public final ObjectMapper mapper;
+  public final ApiInterceptors interceptors = new ApiInterceptors();
+  public final Map<String, Auth> auth = new LinkedHashMap<>();
+
+  public ApiClient(URI baseUri) {
+    this(baseUri, HttpClient.newHttpClient(), defaultMapper());
+  }
+
+  public ApiClient(URI baseUri, HttpClient httpClient, ObjectMapper mapper) {
+    this.baseUri = baseUri;
+    this.httpClient = httpClient;
+    this.mapper = mapper;
+  }
+
+  public static ObjectMapper defaultMapper() {
+    return new ObjectMapper()
+        .registerModule(new JavaTimeModule())
+        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+  }
+
+  public byte[] encode(Object value) {
+    try {
+      return mapper.writeValueAsBytes(value);
+    } catch (IOException e) {
+      throw new IllegalArgumentException("Encoding failed", e);
+    }
+  }
+
+  public <T> T decode(byte[] body, TypeReference<T> type) {
+    try {
+      return mapper.readValue(body, type);
+    } catch (IOException e) {
+      throw ApiException.decoding(e);
+    }
+  }
+
+  public <T> T execute(HttpRequest.Builder request, TypeReference<T> type, RequestOptions options) {
+    return executeWithResponse(request, type, options).body();
+  }
+
+  public <T> ApiResult<T> executeWithResponse(
+      HttpRequest.Builder request, TypeReference<T> type, RequestOptions options) {
+    ApiResult<byte[]> raw = executeRaw(request, options);
+    return new ApiResult<>(decode(raw.body(), type), raw.response());
+  }
+
+  public void executeVoid(HttpRequest.Builder request, RequestOptions options) {
+    executeVoidWithResponse(request, options);
+  }
+
+  public ApiResult<Void> executeVoidWithResponse(
+      HttpRequest.Builder request, RequestOptions options) {
+    HttpResponse<byte[]> response = send(request, options);
+    return new ApiResult<>(null, response);
+  }
+
+  public ApiResult<byte[]> executeRaw(HttpRequest.Builder request, RequestOptions options) {
+    HttpResponse<byte[]> response = send(request, options);
+    byte[] body = response.body();
+    if (options.responseTransformer() != null) body = options.responseTransformer().apply(body);
+    return new ApiResult<>(body, response);
+  }
+
+  private HttpResponse<byte[]> send(HttpRequest.Builder request, RequestOptions options) {
+    HttpRequest.Builder builder = request;
+    for (UnaryOperator<HttpRequest.Builder> interceptor : interceptors.request) {
+      builder = interceptor.apply(builder);
+    }
+    for (UnaryOperator<HttpRequest.Builder> interceptor : options.requestInterceptors()) {
+      builder = interceptor.apply(builder);
+    }
+    if (options.timeout() != null) builder.timeout(options.timeout());
+    HttpResponse<byte[]> response;
+    try {
+      response = httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofByteArray());
+    } catch (IOException e) {
+      throw ApiException.transport(e);
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+      throw ApiException.transport(e);
+    }
+    int status = response.statusCode();
+    if (status < 200 || status >= 300) throw ApiException.forStatus(status, response.body());
+    if (options.responseValidator() != null) {
+      options.responseValidator().accept(response.body(), response);
+    }
+    return response;
+  }
+}

package/runtime/java/ApiException.java

@@ -0,0 +1,39 @@
+package dev.irkit.runtime;
+
+public class ApiException extends RuntimeException {
+  private static final long serialVersionUID = 1L;
+
+  private final int statusCode;
+  private final byte[] body;
+
+  public ApiException(String message, int statusCode, byte[] body, Throwable cause) {
+    super(message, cause);
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+
+  /** HTTP status, or 0 for transport and decoding failures. */
+  public int statusCode() {
+    return statusCode;
+  }
+
+  public byte[] body() {
+    return body;
+  }
+
+  public static ApiException forStatus(int statusCode, byte[] body) {
+    String kind =
+        statusCode >= 400 && statusCode < 500
+            ? "Client error"
+            : statusCode >= 500 && statusCode < 600 ? "Server error" : "Unexpected status";
+    return new ApiException(kind + ": " + statusCode, statusCode, body, null);
+  }
+
+  public static ApiException transport(Throwable cause) {
+    return new ApiException("Transport failure: " + cause.getMessage(), 0, new byte[0], cause);
+  }
+
+  public static ApiException decoding(Throwable cause) {
+    return new ApiException("Decoding failed: " + cause.getMessage(), 0, new byte[0], cause);
+  }
+}

package/runtime/java/ApiInterceptors.java

@@ -0,0 +1,10 @@
+package dev.irkit.runtime;
+
+import java.net.http.HttpRequest;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.UnaryOperator;
+
+public final class ApiInterceptors {
+  public final List<UnaryOperator<HttpRequest.Builder>> request = new ArrayList<>();
+}

package/runtime/java/ApiKeyLocation.java

@@ -0,0 +1,7 @@
+package dev.irkit.runtime;
+
+public enum ApiKeyLocation {
+  HEADER,
+  QUERY,
+  COOKIE
+}

package/runtime/java/ApiResult.java

@@ -0,0 +1,5 @@
+package dev.irkit.runtime;
+
+import java.net.http.HttpResponse;
+
+public record ApiResult<T>(T body, HttpResponse<byte[]> response) {}

package/runtime/java/Auth.java

@@ -0,0 +1,45 @@
+package dev.irkit.runtime;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+public sealed interface Auth permits Auth.Bearer, Auth.ApiKey, Auth.Basic {
+  /** Applies the credential to the request; returns the (possibly rewritten) URI. */
+  URI apply(HttpRequest.Builder builder, URI uri);
+
+  record Bearer(String token) implements Auth {
+    @Override
+    public URI apply(HttpRequest.Builder builder, URI uri) {
+      builder.setHeader("Authorization", "Bearer " + token);
+      return uri;
+    }
+  }
+
+  record ApiKey(String name, String value, ApiKeyLocation location) implements Auth {
+    @Override
+    public URI apply(HttpRequest.Builder builder, URI uri) {
+      switch (location) {
+        case HEADER -> builder.setHeader(name, value);
+        case QUERY -> {
+          return UrlEncoding.appendQuery(
+              uri, UrlEncoding.encode(name) + "=" + UrlEncoding.encode(value));
+        }
+        case COOKIE -> builder.header("Cookie", name + "=" + value);
+      }
+      return uri;
+    }
+  }
+
+  record Basic(String username, String password) implements Auth {
+    @Override
+    public URI apply(HttpRequest.Builder builder, URI uri) {
+      String encoded =
+          Base64.getEncoder()
+              .encodeToString((username + ":" + password).getBytes(StandardCharsets.UTF_8));
+      builder.setHeader("Authorization", "Basic " + encoded);
+      return uri;
+    }
+  }
+}

package/runtime/java/MultipartFormBody.java

@@ -0,0 +1,39 @@
+package dev.irkit.runtime;
+
+import java.io.ByteArrayOutputStream;
+import java.net.http.HttpRequest;
+import java.nio.charset.StandardCharsets;
+import java.util.UUID;
+
+public final class MultipartFormBody {
+  private final String boundary = "irkit-" + UUID.randomUUID();
+  private final ByteArrayOutputStream data = new ByteArrayOutputStream();
+
+  public String contentType() {
+    return "multipart/form-data; boundary=" + boundary;
+  }
+
+  public void appendText(String name, String value) {
+    write("--" + boundary + "\r\n");
+    write("Content-Disposition: form-data; name=\"" + name + "\"\r\n\r\n");
+    write(value + "\r\n");
+  }
+
+  public void appendFile(String name, String filename, byte[] bytes, String mimeType) {
+    write("--" + boundary + "\r\n");
+    write(
+        "Content-Disposition: form-data; name=\"" + name + "\"; filename=\"" + filename + "\"\r\n");
+    write("Content-Type: " + mimeType + "\r\n\r\n");
+    data.writeBytes(bytes);
+    write("\r\n");
+  }
+
+  public HttpRequest.BodyPublisher build() {
+    write("--" + boundary + "--\r\n");
+    return HttpRequest.BodyPublishers.ofByteArray(data.toByteArray());
+  }
+
+  private void write(String text) {
+    data.writeBytes(text.getBytes(StandardCharsets.UTF_8));
+  }
+}

package/runtime/java/QueryStyle.java

@@ -0,0 +1,7 @@
+package dev.irkit.runtime;
+
+public enum QueryStyle {
+  FORM,
+  SPACE_DELIMITED,
+  PIPE_DELIMITED
+}

package/runtime/java/RequestOptions.java

@@ -0,0 +1,106 @@
+package dev.irkit.runtime;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiConsumer;
+import java.util.function.UnaryOperator;
+
+public record RequestOptions(
+    ApiClient client,
+    URI baseUri,
+    Duration timeout,
+    Map<String, String> headers,
+    List<UnaryOperator<HttpRequest.Builder>> requestInterceptors,
+    BiConsumer<byte[], HttpResponse<byte[]>> responseValidator,
+    UnaryOperator<byte[]> responseTransformer) {
+
+  public static RequestOptions defaults() {
+    return new RequestOptions(null, null, null, Map.of(), List.of(), null, null);
+  }
+
+  public RequestOptions withClient(ApiClient client) {
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        headers,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+
+  public RequestOptions withBaseUri(URI baseUri) {
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        headers,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+
+  public RequestOptions withTimeout(Duration timeout) {
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        headers,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+
+  public RequestOptions withHeader(String name, String value) {
+    Map<String, String> next = new LinkedHashMap<>(headers);
+    next.put(name, value);
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        next,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+
+  public RequestOptions withRequestInterceptors(
+      List<UnaryOperator<HttpRequest.Builder>> requestInterceptors) {
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        headers,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+
+  public RequestOptions withResponseValidator(
+      BiConsumer<byte[], HttpResponse<byte[]>> responseValidator) {
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        headers,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+
+  public RequestOptions withResponseTransformer(UnaryOperator<byte[]> responseTransformer) {
+    return new RequestOptions(
+        client,
+        baseUri,
+        timeout,
+        headers,
+        requestInterceptors,
+        responseValidator,
+        responseTransformer);
+  }
+}

package/runtime/java/UrlEncoding.java

@@ -0,0 +1,54 @@
+package dev.irkit.runtime;
+
+import java.net.URI;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.stream.Collectors;
+
+public final class UrlEncoding {
+  private UrlEncoding() {}
+
+  /** Percent-encodes one path segment or query component (spaces as %20). */
+  public static String encode(String value) {
+    return URLEncoder.encode(value, StandardCharsets.UTF_8).replace("+", "%20");
+  }
+
+  /** Appends each segment as its own percent-encoded path component. */
+  public static URI path(URI base, String... segments) {
+    StringBuilder path = new StringBuilder(base.toString().replaceAll("/+$", ""));
+    for (String segment : segments) path.append('/').append(encode(segment));
+    return URI.create(path.toString());
+  }
+
+  public static void addScalar(List<String> query, String name, Object value) {
+    if (value == null) return;
+    query.add(encode(name) + "=" + encode(String.valueOf(value)));
+  }
+
+  public static void addArray(
+      List<String> query, String name, List<?> values, QueryStyle style, boolean explode) {
+    if (values == null) return;
+    if (explode) {
+      for (Object value : values) addScalar(query, name, value);
+      return;
+    }
+    String separator =
+        switch (style) {
+          case FORM -> ",";
+          case SPACE_DELIMITED -> " ";
+          case PIPE_DELIMITED -> "|";
+        };
+    addScalar(
+        query, name, values.stream().map(String::valueOf).collect(Collectors.joining(separator)));
+  }
+
+  public static URI withQuery(URI uri, List<String> query) {
+    return query.isEmpty() ? uri : appendQuery(uri, String.join("&", query));
+  }
+
+  static URI appendQuery(URI uri, String pair) {
+    String text = uri.toString();
+    return URI.create(text + (uri.getRawQuery() == null ? "?" : "&") + pair);
+  }
+}

package/runtime/kotlin/APIClient.kt

@@ -0,0 +1,140 @@
+package dev.irkit.runtime
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import okhttp3.HttpUrl
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import java.util.concurrent.TimeUnit
+
+/**
+ * Runtime helper every per-tag impl class delegates to. Owns the
+ * transport-level concerns — `OkHttpClient`, `Json`, the interceptor
+ * pipeline — and provides one source of truth for status-code
+ * dispatch and decoding.
+ *
+ *  - `execute<T>(request, deserializer, …)`       — decodes a 2xx body to `T`.
+ *  - `executeUnit(request, …)`                    — discards the body.
+ *  - `executeWithResponse<T>(request, deserializer,`
+ *    `…)`                                          — decode + raw `Response`.
+ *  - `executeUnitWithResponse(request, …)`        — raw `Response` only.
+ *  - `executeRaw(request, …)`                     — raw `(ByteArray, Response)`,
+ *                                                    used by multi-2xx ops.
+ *
+ * Status-code dispatch lives in `sendAndDispatch`; 2xx returns the
+ * body bytes, 4xx/5xx throw the matching `APIError` subclass.
+ */
+public class APIClient(
+    public var baseUrl: HttpUrl,
+    public val httpClient: OkHttpClient = OkHttpClient(),
+    public val json: Json =
+        Json {
+            ignoreUnknownKeys = true
+            encodeDefaults = true
+        },
+    public val interceptors: APIInterceptors = APIInterceptors(),
+    public val auth: MutableMap<String, Auth> = mutableMapOf(),
+) {
+    public suspend fun <T> execute(
+        request: Request,
+        deserializer: kotlinx.serialization.DeserializationStrategy<T>,
+        timeout: Long? = null,
+        extraInterceptors: List<suspend (Request) -> Request> = emptyList(),
+        responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+        responseTransformer: (suspend (ByteArray) -> ByteArray)? = null,
+    ): T {
+        val (data, response) = sendAndDispatch(request, timeout, extraInterceptors)
+        responseValidator?.invoke(data, response)
+        val body = responseTransformer?.invoke(data) ?: data
+        return try {
+            json.decodeFromString(deserializer, body.decodeToString())
+        } catch (e: Throwable) {
+            throw APIError.DecodingFailed(e)
+        }
+    }
+
+    public suspend fun executeUnit(
+        request: Request,
+        timeout: Long? = null,
+        extraInterceptors: List<suspend (Request) -> Request> = emptyList(),
+        responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+    ) {
+        val (data, response) = sendAndDispatch(request, timeout, extraInterceptors)
+        responseValidator?.invoke(data, response)
+    }
+
+    public suspend fun <T> executeWithResponse(
+        request: Request,
+        deserializer: kotlinx.serialization.DeserializationStrategy<T>,
+        timeout: Long? = null,
+        extraInterceptors: List<suspend (Request) -> Request> = emptyList(),
+        responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+        responseTransformer: (suspend (ByteArray) -> ByteArray)? = null,
+    ): Pair<T, Response> {
+        val (data, response) = sendAndDispatch(request, timeout, extraInterceptors)
+        responseValidator?.invoke(data, response)
+        val body = responseTransformer?.invoke(data) ?: data
+        return try {
+            json.decodeFromString(deserializer, body.decodeToString()) to response
+        } catch (e: Throwable) {
+            throw APIError.DecodingFailed(e)
+        }
+    }
+
+    public suspend fun executeUnitWithResponse(
+        request: Request,
+        timeout: Long? = null,
+        extraInterceptors: List<suspend (Request) -> Request> = emptyList(),
+        responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+    ): Response {
+        val (data, response) = sendAndDispatch(request, timeout, extraInterceptors)
+        responseValidator?.invoke(data, response)
+        return response
+    }
+
+    public suspend fun executeRaw(
+        request: Request,
+        timeout: Long? = null,
+        extraInterceptors: List<suspend (Request) -> Request> = emptyList(),
+        responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+        responseTransformer: (suspend (ByteArray) -> ByteArray)? = null,
+    ): Pair<ByteArray, Response> {
+        val (data, response) = sendAndDispatch(request, timeout, extraInterceptors)
+        responseValidator?.invoke(data, response)
+        val body = responseTransformer?.invoke(data) ?: data
+        return body to response
+    }
+
+    private suspend fun sendAndDispatch(
+        request: Request,
+        timeout: Long?,
+        extraInterceptors: List<suspend (Request) -> Request>,
+    ): Pair<ByteArray, Response> {
+        var req = request
+        for (interceptor in interceptors.request) req = interceptor(req)
+        for (interceptor in extraInterceptors) req = interceptor(req)
+        val callClient =
+            if (timeout == null) {
+                httpClient
+            } else {
+                httpClient.newBuilder().callTimeout(timeout, TimeUnit.MILLISECONDS).build()
+            }
+        val response =
+            try {
+                withContext(Dispatchers.IO) {
+                    callClient.newCall(req).execute()
+                }
+            } catch (e: Throwable) {
+                throw APIError.Transport(e)
+            }
+        val body = response.body?.bytes() ?: ByteArray(0)
+        return when (val code = response.code) {
+            in 200..299 -> body to response
+            in 400..499 -> throw APIError.ClientError(code, body)
+            in 500..599 -> throw APIError.ServerError(code, body)
+            else -> throw APIError.UnexpectedStatus(code, body)
+        }
+    }
+}

package/runtime/kotlin/APIError.kt

@@ -0,0 +1,42 @@
+package dev.irkit.runtime
+
+/**
+ * The typed error every impl method throws on non-2xx responses.
+ *
+ *  - `ClientError(statusCode, body)`     — 4XX
+ *  - `ServerError(statusCode, body)`     — 5XX
+ *  - `UnexpectedStatus(statusCode, body)` — 1XX/3XX/anything outside 2-5
+ *  - `DecodingFailed(cause)`             — kotlinx-serialization threw on a 2XX body
+ *  - `Transport(cause)`                  — OkHttp / network-layer failure
+ *
+ * Consumers `catch` and pattern-match. Bodies are surfaced as raw
+ * `ByteArray` so callers can decode error envelopes themselves with the
+ * codec they prefer.
+ */
+public sealed class APIError(
+    message: String? = null,
+    cause: Throwable? = null,
+) : RuntimeException(message, cause) {
+    public class ClientError(
+        public val statusCode: Int,
+        public val body: ByteArray,
+    ) : APIError("Client error: $statusCode")
+
+    public class ServerError(
+        public val statusCode: Int,
+        public val body: ByteArray,
+    ) : APIError("Server error: $statusCode")
+
+    public class UnexpectedStatus(
+        public val statusCode: Int,
+        public val body: ByteArray,
+    ) : APIError("Unexpected status: $statusCode")
+
+    public class DecodingFailed(
+        cause: Throwable,
+    ) : APIError("Decoding failed: ${cause.message}", cause)
+
+    public class Transport(
+        cause: Throwable,
+    ) : APIError("Transport failure: ${cause.message}", cause)
+}

package/runtime/kotlin/APIInterceptors.kt

@@ -0,0 +1,14 @@
+package dev.irkit.runtime
+
+import okhttp3.Request
+
+/**
+ * Bag of per-request mutation hooks. Mirrors hey-api's TS client where
+ * `client.interceptors.request.use(fn)` registers an interceptor that
+ * runs against every outgoing request. Multiple interceptors compose —
+ * auth, logging, and tracing all coexist as separate entries instead
+ * of being chained inside one closure.
+ */
+public class APIInterceptors {
+    public val request: MutableList<suspend (Request) -> Request> = mutableListOf()
+}

package/runtime/kotlin/APIKeyLocation.kt

@@ -0,0 +1,7 @@
+package dev.irkit.runtime
+
+public enum class APIKeyLocation {
+    HEADER,
+    QUERY,
+    COOKIE,
+}