v2.0.0

Author: Swarkin

.gitattributes

@@ -1,4 +1,4 @@
 * text=auto eol=lf
 
-/**                         export-ignore
-/AwaitableHTTPRequest.gd    !export-ignore
+/.gitattributes export-ignore
+/README.md      export-ignore

.gitignore

@@ -1,5 +1,30 @@
-The AwaitableHTTPRequest Node allows you to make a HTTP request with one line of code!
+<img alt="project icon: syntax-highlighted text reading 'await http dot request()'" src="addons/awaitable_http_request/icon.png" width="64">
 
-![Usage](example.png)
+## AwaitableHTTPRequest Node for Godot 4
 
-This script can be found on the [Godot AssetLib](https://godotengine.org/asset-library/asset/2502).
+This addon makes HTTP requests much more convenient to use by introducing the `await`-syntax and removing the need for signals.
+
+### Usage
+
+Here is an example with minimal error-handling:
+
+```py
+@export var http: AwaitableHTTPRequest
+
+func _ready() -> void:
+    var resp := await http.async_request("https://api.github.com/users/swarkin")
+    if resp.success():
+        print(resp.status)                   # 200
+        print(resp.headers["content-type"])  # application/json
+
+        var json := resp.body_as_json()
+        print(json["login"])                 # Swarkin
+```
+
+See `examples.tscn` for more.
+
+---
+
+> Available on the [Godot Asset Library](https://godotengine.org/asset-library/asset/2502)
+
+<sub>Requires Godot 4.1</sub>

AwaitableHTTPRequest.gd

@@ -0,0 +1,43 @@
+class_name AwaitableHTTPRequest
+extends HTTPRequest
+## [img width=64]res://addons/awaitable_http_request/icon.png[/img]   [url=https://github.com/Swarkin/Godot-AwaitableHTTPRequest]AwaitableHTTPRequest[/url] 2.0.0 by Swarkin & [url=https://github.com/Swarkin/Godot-AwaitableHTTPRequest/graphs/contributors]contributors[/url].
+# View the formatted documentation in Godot by pressing F1 and typing "AwaitableHTTPRequest"!
+
+signal request_finished     ## Emits once the current request finishes, right after [member is_requesting] is set to false.
+var is_requesting := false  ## Whether the node is busy performing a request. This variable is read-only.
+
+## Performs an awaitable HTTP request.[br]
+## Take a look at the [code]examples.tscn[/code] scene in the addon directory for inspiration![br]
+## [br]
+## [b]Note:[/b] Header names will be in lowercase, as some web servers prefer this approach and them being case-insensitive as per specification. Therefore, it is good practice to not rely on capitalization.
+## [br]
+## Here is an example with minimal error-handling:
+## [codeblock]
+## @export var http: AwaitableHTTPRequest
+##
+## func _ready() -> void:
+##     var resp := await http.async_request("https://api.github.com/users/swarkin")
+##     if resp.success():
+##         print(resp.status)                   # 200
+##         print(resp.headers["content-type"])  # application/json
+##
+##         var json := resp.body_as_json()
+##         print(json["login"])                 # Swarkin
+## [/codeblock]
+func async_request(url: String, custom_headers := PackedStringArray(), method := HTTPClient.Method.METHOD_GET, request_data := "") -> HTTPResult:
+	if is_requesting:
+		push_error("AwaitableHTTPRequest is busy performing a request.")
+		return
+
+	is_requesting = true
+
+	var err := request(url, custom_headers, method, request_data)
+	if err:
+		return HTTPResult._from_error(err)
+
+	@warning_ignore("unsafe_cast")
+	var result := await request_completed as Array
+	is_requesting = false
+	request_finished.emit()
+
+	return HTTPResult._from_array(result)

README.md

@@ -0,0 +1,80 @@
+[gd_scene load_steps=3 format=3 uid="uid://bnqsp15ey3wrl"]
+
+[ext_resource type="Script" path="res://addons/awaitable_http_request/awaitable_http_request.gd" id="1_b05hb"]
+
+[sub_resource type="GDScript" id="GDScript_qphse"]
+resource_name = "example"
+script/source = "extends Node
+
+@export var http: AwaitableHTTPRequest
+
+
+func _ready() -> void:
+	print(\"Example 1: JSON API\")
+	var data := await request_api()
+	if not data.is_empty():
+		var user := data[\"login\"] as String
+		print(\"User: \", user)
+
+	print(\"\\nExample 2: Downloading an image\")
+	var bytes := await request_image()
+	if not bytes.is_empty():
+		# Snippet for loading a PackedByteArray into an Image,
+		# as well as an ImageTexture to use in your app/game.
+		#var img := Image.new()
+		#img.load_png_from_buffer(bytes)
+		#var tex := ImageTexture.create_from_image(img)
+
+		var path := OS.get_system_dir(OS.SYSTEM_DIR_DOWNLOADS)+\"/image.png\"
+		var file := FileAccess.open(path, FileAccess.WRITE)
+		if not file:
+			push_error(\"Failed to save image.\")
+			return
+
+		file.store_buffer(bytes)
+		print(\"Downloaded and saved a random image to %s, take a look!\" % path)
+
+
+#region Example 1: JSON API
+func request_api() -> Dictionary:
+	var resp := await http.async_request(
+		\"https://api.github.com/users/swarkin\",
+		PackedStringArray([ # headers
+			\"accept: application/vnd.github+json\",
+			\"user-agent: Swarkin/AwaitableHTTPRequest/2.0.0\",
+		]),
+	)
+
+	if !resp.success() or resp.status_err():
+		push_error(\"Request failed.\")
+		return {}
+
+	print(\"Status code: \", resp.status)
+	print(\"Content-Type:\", resp.headers[\"content-type\"])
+
+	var json := resp.body_as_json()
+	if not json:
+		push_error(\"JSON invalid.\")
+		return {}
+
+	return json as Dictionary
+#endregion
+
+#region Example 2: Downloading an image
+func request_image() -> PackedByteArray:
+	var resp := await http.async_request(\"https://picsum.photos/256\")
+	if !resp.success() or resp.status_err():
+		push_error(\"Request failed.\")
+		return PackedByteArray()
+
+	return resp.bytes
+#endregion
+"
+
+[node name="Press F6 to run examples" type="Node" node_paths=PackedStringArray("http")]
+editor_description = "This scene is not required and may be deleted freely."
+script = SubResource("GDScript_qphse")
+http = NodePath("AwaitableHTTPRequest")
+
+[node name="AwaitableHTTPRequest" type="HTTPRequest" parent="."]
+script = ExtResource("1_b05hb")

LICENSE renamed to addons/awaitable_http_request/LICENSE

@@ -0,0 +1,60 @@
+class_name HTTPResult
+extends RefCounted
+## A dataclass returned by [method AwaitableHTTPRequest.async_request].
+
+var _error: Error				## Contains the [method HTTPRequest.request] error, [constant Error.OK] otherwise. See also [method success].[br](For advanced use-cases)
+var _result: HTTPRequest.Result	## Contains the [annotation HTTPRequest] error, [constant HTTPRequest.RESULT_SUCCESS] otherwise. See also [method success].[br](For advanced use-cases)
+var status: int					## The response status code.
+var headers: Dictionary			## The response headers.
+var bytes: PackedByteArray		## The response body as a [PackedByteArray].[br][b]Note:[/b] Any [Array] is always passed by reference.
+
+## Checks whether the HTTP request succeeded, meaning [member _error] and [member _result] aren't in an error state.[br]
+## [b]Note:[/b] This does not check the response [member status] code.
+func success() -> bool:
+	return _error == OK and _result == HTTPRequest.RESULT_SUCCESS
+
+## Checks whether the [member status] is between 200 and 299 (inclusive), see [url]https://developer.mozilla.org/en-US/docs/Web/HTTP/Status[/url].
+func status_ok() -> bool:
+	return status >= 200 and status < 300
+
+## Checks whether the [member status] is between 400 and 599 (inclusive), see [url]https://developer.mozilla.org/en-US/docs/Web/HTTP/Status[/url].
+func status_err() -> bool:
+	return status >= 400 and status < 599
+
+## The response body as a [String].[br]
+## For other formatting (ascii, utf16, ...) or special use-cases (file I/O, ...), it is possible to access the raw body's [member bytes].[br]
+## You should cache this return value instead of calling the funciton multiple times.
+func body_as_string() -> String:
+	return bytes.get_string_from_utf8()
+
+## Attempt to parse the response [member bytes] into a [Dictionary] or [Array], returns null on failure.[br][br]
+## It is possible to cast the return type to a [Dictionary] with "[code]as Dictionary[/code]" to receive autocomplete and other benefits when the parsing was successful.[br]
+## If you want error handling for the JSON deserialization, make an instance of [JSON] and call [method JSON.parse] on it, passing in the return value of [method HTTPResult.body_as_string]. This allows the usage of [method JSON.get_error_message] and [method JSON.get_error_line] to get potential error information.[br][br]
+## [b]Note:[/b] Godot always converts JSON numbers to [float]s!
+func body_as_json() -> Variant:
+	return JSON.parse_string(body_as_string())
+
+# Constructs a new [HTTPResult] from an [enum @GlobalScope.Error] code. (Used internally, hidden from API list)
+static func _from_error(err: Error) -> HTTPResult:
+	var h := HTTPResult.new()
+	h._error = err
+	return h
+
+# Constructs a new [HTTPResult] from the return value of [signal HTTPRequest.request_completed]. (Used internally, hidden from API list)
+@warning_ignore("unsafe_cast")
+static func _from_array(a: Array) -> HTTPResult:
+	var h := HTTPResult.new()
+	h._result = a[0] as HTTPRequest.Result
+	h.status = a[1] as int
+	h.headers = _headers_to_dict(a[2] as PackedStringArray)
+	h.bytes = a[3] as PackedByteArray
+	return h
+
+# Converts a [PackedStringArray] of headers into a [Dictionary]. The header names will be in lowercase, as some web servers prefer this approach and them being case-insensitive as per specification. Therefore, it is good practice to not rely on capitalization. (Used internally, hidden from API list)
+static func _headers_to_dict(headers_arr: PackedStringArray) -> Dictionary:
+	var dict := {}
+	for h in headers_arr:
+		var split := h.split(":")
+		dict[split[0].to_lower()] = split[1].strip_edges()
+
+	return dict