366 lines
11 KiB
GDScript
366 lines
11 KiB
GDScript
class_name ApiClient
|
|
extends Node
|
|
## @group Networking
|
|
## @description Central HTTP client singleton that wraps Godot's HTTPRequest node.
|
|
##
|
|
## Every network call flows through this class. Callers use the high-level
|
|
## helpers (login, register, get_worlds, etc.) or the generic request()
|
|
## primitive. All results conform to the [result-dictionary] contract below.
|
|
##
|
|
## ## Result Dictionary Contract
|
|
## Every public method returns a Dictionary with this shape:
|
|
##
|
|
## {
|
|
## "ok": bool, # true for HTTP 2xx, false otherwise
|
|
## "status": int, # HTTP status code (0 on network failure)
|
|
## "data": Variant, # parsed JSON body on success
|
|
## "detail": String, # human-readable error message
|
|
## }
|
|
##
|
|
## Network failures (timeout, DNS, refused connection) return status=0 with
|
|
## a detail describing the failure. Non-2xx responses return the actual status
|
|
## code and the backend's "detail" field from the JSON error body.
|
|
##
|
|
## ## Token Storage
|
|
## JWT bearer tokens are kept in memory. The [method set_token] method is
|
|
## the single seam for token persistence — override it to save to disk.
|
|
##
|
|
## ## Usage
|
|
## var result = await ApiClient.login("alice", "secret")
|
|
## if result.ok:
|
|
## print("Logged in!")
|
|
## else:
|
|
## print("Error: ", result.detail)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Token storage
|
|
# ---------------------------------------------------------------------------
|
|
|
|
var _access_token: String = ""
|
|
var _token_type: String = "Bearer"
|
|
|
|
## Current bearer token string (e.g. "Bearer eyJ...").
|
|
## Read-only — use [method set_token] to change.
|
|
var bearer_token: String:
|
|
get:
|
|
return _token_type + " " + _access_token if _access_token else ""
|
|
|
|
## Whether a token has been set.
|
|
func has_token() -> bool:
|
|
return _access_token != ""
|
|
|
|
## Set the access token (called after login / token refresh).
|
|
## @param access_token The raw JWT string from the server.
|
|
## @param token_type Token type, defaults to "Bearer".
|
|
func set_token(access_token: String, token_type: String = "Bearer") -> void:
|
|
_access_token = access_token
|
|
_token_type = token_type
|
|
|
|
## Clear stored tokens.
|
|
func clear_token() -> void:
|
|
_access_token = ""
|
|
_token_type = "Bearer"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Internal HTTPRequest node
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## The internal HTTPRequest node. Created lazily on first use.
|
|
var _http_request: HTTPRequest
|
|
|
|
## Base URL read from project settings.
|
|
var _base_url: String
|
|
|
|
# Signal emitted when a request completes. The argument is the result dict.
|
|
signal request_completed(result: Dictionary)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Lifecycle
|
|
# ---------------------------------------------------------------------------
|
|
|
|
func _ready() -> void:
|
|
# Read base URL from project settings, fall back to localhost:8000.
|
|
_base_url = ProjectSettings.get_setting(
|
|
"application/agp/api_base_url",
|
|
"http://127.0.0.1:8000"
|
|
)
|
|
# Ensure the setting exists so it appears in the editor.
|
|
if not ProjectSettings.has_setting("application/agp/api_base_url"):
|
|
ProjectSettings.set_setting("application/agp/api_base_url", _base_url)
|
|
ProjectSettings.save()
|
|
|
|
func _enter_tree() -> void:
|
|
_http_request = HTTPRequest.new()
|
|
_http_request.timeout = 10.0
|
|
_http_request.max_redirects = 8
|
|
_http_request.accept_gzip = true
|
|
add_child(_http_request)
|
|
_http_request.request_completed.connect(_on_http_request_completed)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Core request primitive
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## Generic request method.
|
|
##
|
|
## @param method HTTPClient.Method enum value (GET, POST, PUT, DELETE).
|
|
## @param path URL path (e.g. "/api/health").
|
|
## @param body Request body as String (JSON or form-encoded).
|
|
## @param content_type "application/json" or "application/x-www-form-urlencoded".
|
|
## @param require_auth If true, attach bearer token header.
|
|
## @return A result dictionary conforming to the contract.
|
|
func request(
|
|
method: HTTPClient.Method,
|
|
path: String,
|
|
body: String = "",
|
|
content_type: String = "application/json",
|
|
require_auth: bool = false
|
|
) -> Dictionary:
|
|
var url: String = _base_url + path
|
|
|
|
# Build headers.
|
|
var headers: PackedStringArray = PackedStringArray()
|
|
headers.append("Content-Type: " + content_type)
|
|
if require_auth and has_token():
|
|
headers.append("Authorization: " + bearer_token)
|
|
|
|
# Fire the request.
|
|
var err: int = _http_request.request(url, headers, method, body)
|
|
if err != OK:
|
|
return _network_error(err, "Failed to start request: " + _error_string(err))
|
|
|
|
# Wait for completion.
|
|
var result_data = await request_completed
|
|
return result_data
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Signal handler
|
|
# ---------------------------------------------------------------------------
|
|
|
|
func _on_http_request_completed(
|
|
result: int,
|
|
response_code: int,
|
|
headers: PackedStringArray,
|
|
body: PackedByteArray
|
|
) -> void:
|
|
# result == HTTPRequest.RESULT_SUCCESS means the transport succeeded.
|
|
# response_code == 0 means no response was received (e.g. timeout).
|
|
if result != HTTPRequest.RESULT_SUCCESS:
|
|
var detail: String = _network_error_detail(result)
|
|
var dict: Dictionary = {
|
|
"ok": false,
|
|
"status": 0,
|
|
"data": null,
|
|
"detail": detail,
|
|
}
|
|
request_completed.emit(dict)
|
|
return
|
|
|
|
if response_code == 0:
|
|
var dict: Dictionary = {
|
|
"ok": false,
|
|
"status": 0,
|
|
"data": null,
|
|
"detail": "No response received from server.",
|
|
}
|
|
request_completed.emit(dict)
|
|
return
|
|
|
|
# Parse JSON body.
|
|
var json_string: String = body.get_string_from_utf8()
|
|
var data = null
|
|
var detail: String = ""
|
|
|
|
if response_code >= 200 and response_code < 300:
|
|
# Success — try to parse JSON.
|
|
var parse_result = JSON.parse_string(json_string)
|
|
if parse_result is Dictionary:
|
|
data = parse_result
|
|
# Extract backend detail if present.
|
|
if data.has("detail"):
|
|
detail = str(data["detail"])
|
|
else:
|
|
detail = "OK"
|
|
else:
|
|
data = json_string
|
|
detail = "OK"
|
|
else:
|
|
# Error response — try to extract detail from JSON.
|
|
var parse_result = JSON.parse_string(json_string)
|
|
if parse_result is Dictionary:
|
|
detail = str(parse_result.get("detail", "HTTP error %d" % response_code))
|
|
else:
|
|
detail = "HTTP error %d" % response_code
|
|
|
|
var dict: Dictionary = {
|
|
"ok": response_code >= 200 and response_code < 300,
|
|
"status": response_code,
|
|
"data": data,
|
|
"detail": detail,
|
|
}
|
|
request_completed.emit(dict)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# High-level helpers
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## Login with username and password.
|
|
##
|
|
## Sends a POST to /api/auth/login with form-encoded credentials
|
|
## (OAuth2PasswordRequestForm format). On success, stores the token.
|
|
##
|
|
## @param username The user's username.
|
|
## @param password The user's password.
|
|
## @return Result dictionary.
|
|
func login(username: String, password: String) -> Dictionary:
|
|
var form_data: String = "username=" + username.uri_encode() + "&password=" + password.uri_encode()
|
|
var result = await request(
|
|
HTTPClient.METHOD_POST,
|
|
"/api/auth/login",
|
|
form_data,
|
|
"application/x-www-form-urlencoded",
|
|
false
|
|
)
|
|
if result.ok and result.data is Dictionary:
|
|
var access_token = result.data.get("access_token", "")
|
|
if access_token != "":
|
|
set_token(access_token)
|
|
return result
|
|
|
|
## Register a new user.
|
|
##
|
|
## Sends a POST to /api/auth/register with JSON body.
|
|
## On success, stores the returned token.
|
|
##
|
|
## @param username The desired username.
|
|
## @param email The user's email address.
|
|
## @param password The desired password.
|
|
## @param date_of_birth Date of birth in YYYY-MM-DD format.
|
|
## @return Result dictionary.
|
|
func register(
|
|
username: String,
|
|
email: String,
|
|
password: String,
|
|
date_of_birth: String
|
|
) -> Dictionary:
|
|
var payload: Dictionary = {
|
|
"username": username,
|
|
"email": email,
|
|
"password": password,
|
|
"date_of_birth": date_of_birth,
|
|
}
|
|
var json_body: String = JSON.stringify(payload)
|
|
var result = await request(
|
|
HTTPClient.METHOD_POST,
|
|
"/api/auth/register",
|
|
json_body,
|
|
"application/json",
|
|
false
|
|
)
|
|
if result.ok and result.data is Dictionary:
|
|
var access_token = result.data.get("access_token", "")
|
|
if access_token != "":
|
|
set_token(access_token)
|
|
return result
|
|
|
|
## List worlds visible to the current user.
|
|
##
|
|
## Sends a GET to /api/worlds/ with the bearer token.
|
|
##
|
|
## @param skip Number of worlds to skip (pagination offset).
|
|
## @param limit Maximum number of worlds to return.
|
|
## @param visibility Optional filter: "public", "private", or "friends_only".
|
|
## @return Result dictionary.
|
|
func get_worlds(
|
|
skip: int = 0,
|
|
limit: int = 50,
|
|
visibility: String = ""
|
|
) -> Dictionary:
|
|
var path: String = "/api/worlds/?skip=%d&limit=%d" % [skip, limit]
|
|
if visibility != "":
|
|
path += "&visibility=" + visibility.uri_encode()
|
|
return await request(
|
|
HTTPClient.METHOD_GET,
|
|
path,
|
|
"",
|
|
"application/json",
|
|
true
|
|
)
|
|
|
|
## Check the server health endpoint.
|
|
##
|
|
## @return Result dictionary.
|
|
func health_check() -> Dictionary:
|
|
return await request(
|
|
HTTPClient.METHOD_GET,
|
|
"/api/health",
|
|
"",
|
|
"application/json",
|
|
false
|
|
)
|
|
|
|
## Get current user profile.
|
|
##
|
|
## @return Result dictionary.
|
|
func get_me() -> Dictionary:
|
|
return await request(
|
|
HTTPClient.METHOD_GET,
|
|
"/api/users/me",
|
|
"",
|
|
"application/json",
|
|
true
|
|
)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Persistence seam
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## Called before the node is freed. Override to persist tokens to disk.
|
|
func _exit_tree() -> void:
|
|
# TODO: Save tokens to disk (e.g. user://tokens.cfg).
|
|
pass
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Helpers
|
|
# ---------------------------------------------------------------------------
|
|
|
|
func _network_error(err_code: int, fallback: String) -> Dictionary:
|
|
return {
|
|
"ok": false,
|
|
"status": 0,
|
|
"data": null,
|
|
"detail": fallback,
|
|
}
|
|
|
|
func _network_error_detail(result_code: int) -> String:
|
|
match result_code:
|
|
HTTPRequest.RESULT_CANT_CONNECT:
|
|
return "Could not connect to server. Is it running?"
|
|
HTTPRequest.RESULT_CANT_RESOLVE:
|
|
return "Could not resolve server hostname."
|
|
HTTPRequest.RESULT_CONNECTION_ERROR:
|
|
return "Connection error."
|
|
HTTPRequest.RESULT_TLS_HANDSHAKE_ERROR:
|
|
return "TLS handshake failed."
|
|
HTTPRequest.RESULT_NO_RESPONSE:
|
|
return "No response from server."
|
|
HTTPRequest.RESULT_TIMEOUT:
|
|
return "Request timed out."
|
|
_:
|
|
return "Network error (code %d)." % result_code
|
|
|
|
func _error_string(err_code: int) -> String:
|
|
match err_code:
|
|
OK:
|
|
return "OK"
|
|
ERR_UNCONFIGURED:
|
|
return "HTTPRequest not configured (not in tree)."
|
|
ERR_BUSY:
|
|
return "HTTPRequest is busy with a previous request."
|
|
ERR_INVALID_PARAMETER:
|
|
return "Invalid URL format."
|
|
ERR_CANT_CONNECT:
|
|
return "Cannot connect to host."
|
|
_:
|
|
return "Unknown error (%d)." % err_code
|