HTTP Client - Refinery WIKI

xyz.refineryteam.refinerycore.api.http.Http is a minimal async HTTP client for plugin-sized needs: update checks, Discord webhooks, REST APIs. Requests run on a dedicated daemon pool — never the common ForkJoinPool and never the main thread — with retry/backoff scheduled through your plugin’s async scheduler.

Quick start

UpdateChecker.java

Http http = Http.of(plugin);

// GET with a header
http.get("https://api.example.com/version")
    .header("Authorization", "Bearer " + token)
    .executeAsync()
    .thenAccept(response -> {
        if (response.ok()) handle(response.body());
    });

// POST a JSON body (e.g. a Discord webhook) with retries
http.post(webhookUrl)
    .jsonBody("{\"content\":\"Server started\"}")
    .retries(2)
    .executeAsync();

Call http.close() from onDisable() if you own the instance — safe to skip, since the worker threads are daemons.

Building requests

Start with get(url), post(url), put(url), or delete(url), then configure the fluent Request builder:

Method	Description
`header(String name, String value)`	Adds a request header (e.g. `"Authorization"`)
`jsonBody(String json)`	Sets a JSON body and the `application/json` content type in one call
`body(String body, String contentType)`	Sets an arbitrary body with an explicit MIME type (e.g. `"text/plain"`)
`formBody(Map<String, String> fields)`	Form-encoded convenience: builds `key1=value1&key2=value2` with URL encoding and the matching content type
`retries(int count)`	How many times to retry on `IOException` or a 5xx status. Backoff is exponential: 500ms, 1s, 2s…
`timeout(Duration)`	Per-attempt timeout (default 15 seconds)
`executeAsync()`	Executes asynchronously, returning a `CompletableFuture<Response>` after any retries. Never blocks the calling thread and never throws — errors arrive as a completed-exceptionally future
`execute()`	Blocking variant for use off the main thread only. Transport failures yield a response with status `-1` and the error attached

Responses

executeAsync() completes with a Response record:

Member	Description
`statusCode()`	HTTP status code, or `-1` on transport failure
`body()`	Response body as a string
`ok()`	Whether the status code is in the 2xx range
`error()`	The throwable behind a transport failure, or `null`

Never call the blocking execute() from the main thread — network latency will freeze the server tick. Use executeAsync() and react in the future’s callback, or hop off the thread first with RefineryScheduler.

For anything heavier — connection pooling tuning, multipart uploads, streaming — reach for a dedicated HTTP library. Http intentionally covers the simple request/response cases well and nothing else.

​Quick start

​Building requests

​Responses

Quick start

Building requests

Responses