refacto(gdscript, breaking): use an ApiResponse object in success callbacks

/spent 6d since the beginning

Author: Goutte

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/GdscriptClientCodegen.java

@@ -253,6 +253,7 @@ public void processOpts() {
         supportingFiles.add(new SupportingFile("ApiBee.handlebars", "core", toCoreFilename("ApiBee") + ".gd"));
         supportingFiles.add(new SupportingFile("ApiError.handlebars", "core", toCoreFilename("ApiError") + ".gd"));
         supportingFiles.add(new SupportingFile("ApiConfig.handlebars", "core", toCoreFilename("ApiConfig") + ".gd"));
+        supportingFiles.add(new SupportingFile("core/ApiResponse.handlebars", "core", toCoreFilename("ApiResponse") + ".gd"));
         supportingFiles.add(new SupportingFile("README.handlebars", "", "README.md"));
 
         // Ensure we're using the appropriate template engine, and configure it while we're at it.

modules/openapi-generator/src/main/resources/gdscript/ApiBee.handlebars

@@ -1,35 +1,37 @@
-{{! TODO: would be nice to be able to customize parent class from CLI }}
-extends RefCounted
+extends {{>partials/api_bee_parent_class}}
 class_name {{>partials/api_base_class_name}}
 
-# Base class for all generated API endpoints.
+{{>partials/disclaimer_autogenerated}}
+
+# Base class for all generated API endpoints
+# ==========================================
 #
 # Every property/method defined here may collide with userland,
 # so these are all listed and excluded in our CodeGen Java file.
 # We want to keep the amount of renaming to a minimum, though.
 # Therefore, we use the _bzz_ prefix, even if awkward.
 
 
-const BEE_CONTENT_TYPE_TEXT := "text/plain"
-const BEE_CONTENT_TYPE_HTML := "text/html"
-const BEE_CONTENT_TYPE_JSON := "application/json"
-const BEE_CONTENT_TYPE_FORM := "application/x-www-form-urlencoded"
-const BEE_CONTENT_TYPE_JSONLD := "application/json+ld"  # unsupported (for now)
-const BEE_CONTENT_TYPE_XML := "application/xml"  # unsupported (for now)
+const BZZ_CONTENT_TYPE_TEXT := "text/plain"
+const BZZ_CONTENT_TYPE_HTML := "text/html"
+const BZZ_CONTENT_TYPE_JSON := "application/json"
+const BZZ_CONTENT_TYPE_FORM := "application/x-www-form-urlencoded"
+const BZZ_CONTENT_TYPE_JSONLD := "application/json+ld"  # unsupported (for now)
+const BZZ_CONTENT_TYPE_XML := "application/xml"  # unsupported (for now)
 
 # From this client's point of view.
 # Adding a content type here won't magically make the client support it, but you may reorder.
 # These are sorted by decreasing preference. (first → preferred)
-const BEE_PRODUCIBLE_CONTENT_TYPES := [
-	BEE_CONTENT_TYPE_JSON,
-	BEE_CONTENT_TYPE_FORM,
+const BZZ_PRODUCIBLE_CONTENT_TYPES := [
+	BZZ_CONTENT_TYPE_JSON,
+	BZZ_CONTENT_TYPE_FORM,
 ]
 
 # From this client's point of view.
 # Adding a content type here won't magically make the client support it, but you may reorder.
 # These are sorted by decreasing preference. (first → preferred)
-const BEE_CONSUMABLE_CONTENT_TYPES := [
-	BEE_CONTENT_TYPE_JSON,
+const BZZ_CONSUMABLE_CONTENT_TYPES := [
+	BZZ_CONTENT_TYPE_JSON,
 ]
 
 
@@ -56,6 +58,7 @@ var _bzz_config: {{>partials/api_config_class_name}}:
 		return _bzz_config
 
 
+# Useful in logs
 var _bzz_name: String:
 	get:
 		return _bzz_get_api_name()
@@ -130,7 +133,7 @@ func _bzz_connect_client_if_needed(
 	if connected != HTTPClient.STATUS_CONNECTED:
 		var error := {{>partials/api_error_class_name}}.new()
 		error.internal_code = connected as Error
-		error.identifier = "apibee.connect_to_host.wrong_status"
+		error.identifier = "apibee.connect_to_host.status_failure"
 		error.message = "%s: failed to connect to `%s' port `%d' : %s" % [
 			_bzz_name, self._bzz_config.host, self._bzz_config.port,
 			_bzz_httpclient_status_string(connected),
@@ -141,32 +144,32 @@ func _bzz_connect_client_if_needed(
 	on_success.call()
 
 
-func bzz_request(
+func _bzz_request(
 	method: int,  # one of HTTPClient.METHOD_XXXXX
 	path: String,
 	headers: Dictionary,
 	query: Dictionary,
 	body,  # Variant that will be serialized and sent
-	on_success: Callable,  # func(response: Variant, responseCode: int, responseHeaders: Dictionary)
+	on_success: Callable,  # func(response: {{>partials/api_response_class_name}})
 	on_failure: Callable,  # func(error: {{>partials/api_error_class_name}})
 ):
 	# This method does not handle full deserialization, it only handles decode and not denormalization.
 	# Denormalization is handled in each generated API endpoint in the on_success callable of this method.
-	# This is because this method already has plethora of parameters and we don't want even more.
 
 	_bzz_request_text(
 		method, path, headers, query, body,
-		func(responseText, responseCode, responseHeaders):
-			var mime: String = responseHeaders['Mime']
-			var decodedResponse  # Variant
-
-			if BEE_CONTENT_TYPE_TEXT == mime:
-				decodedResponse = responseText
-			elif BEE_CONTENT_TYPE_HTML == mime:
-				decodedResponse = responseText
-			elif BEE_CONTENT_TYPE_JSON == mime:
+		func(response):
+			var mime: String = response.headers['Mime']
+			var decodedBody  # Variant
+
+			# Isn't there a match/case now in Gdscript?
+			if BZZ_CONTENT_TYPE_TEXT == mime:
+				decodedBody = response.body
+			elif BZZ_CONTENT_TYPE_HTML == mime:
+				decodedBody = response.body
+			elif BZZ_CONTENT_TYPE_JSON == mime:
 				var parser := JSON.new()
-				var parsing := parser.parse(responseText)
+				var parsing := parser.parse(response.body)
 				if OK != parsing:
 					var error := {{>partials/api_error_class_name}}.new()
 					error.internal_code = parsing
@@ -176,18 +179,19 @@ func bzz_request(
 					]
 					on_failure.call(error)
 					return
-				decodedResponse = parser.data
+				decodedBody = parser.data
 			else:
 				var error := {{>partials/api_error_class_name}}.new()
 				error.internal_code = ERR_INVALID_DATA
 				error.identifier = "apibee.decode.mime_type_unsupported"
-				error.message = "%s: mime type `%s' is not supported (yet)" % [
+				error.message = "%s: mime type `%s' is not supported (yet -- MRs welcome)" % [
 					_bzz_name, mime
 				]
 				on_failure.call(error)
 				return
 
-			on_success.call(decodedResponse, responseCode, responseHeaders)
+			response.data = decodedBody
+			on_success.call(response)
 			,
 		func(error):
 			on_failure.call(error)
@@ -201,7 +205,7 @@ func _bzz_request_text(
 	headers: Dictionary,
 	query: Dictionary,
 	body,  # Variant that will be serialized
-	on_success: Callable,  # func(responseText: String, responseCode: int, responseHeaders: Dictionary)
+	on_success: Callable,  # func(response: {{>partials/api_response_class_name}})
 	on_failure: Callable,  # func(error: {{>partials/api_error_class_name}})
 ):
 	_bzz_connect_client_if_needed(
@@ -220,7 +224,7 @@ func _bzz_do_request_text(
 	headers: Dictionary,
 	query: Dictionary,
 	body,  # Variant that will be serialized
-	on_success: Callable,  # func(responseText: String, responseCode: int, responseHeaders: Dictionary)
+	on_success: Callable,  # func(response: {{>partials/api_response_class_name}})
 	on_failure: Callable,  # func(error: {{>partials/api_error_class_name}})
 ):
 
@@ -245,9 +249,9 @@ func _bzz_do_request_text(
 
 	var body_serialized := ""
 	var content_type := self._bzz_get_content_type(headers)
-	if content_type == BEE_CONTENT_TYPE_JSON:
+	if content_type == BZZ_CONTENT_TYPE_JSON:
 		body_serialized = JSON.stringify(body_normalized)
-	elif content_type == BEE_CONTENT_TYPE_FORM:
+	elif content_type == BZZ_CONTENT_TYPE_FORM:
 		body_serialized = self._bzz_client.query_string_from_dict(body_normalized)
 	else:
 		# TODO: Handle other serialization schemes (json+ld, xml…)
@@ -297,15 +301,18 @@ func _bzz_do_request_text(
 		on_failure.call(error)
 		return
 
-	var response_code := self._bzz_client.get_response_code()
-	var response_headers := self._bzz_client.get_response_headers_as_dictionary()
+	var response := {{>partials/api_response_class_name}}.new()
+	#response.collect_meta_from_client(self._bzz_client)  # to refactor
+	response.code = self._bzz_client.get_response_code()
+	response.headers = self._bzz_client.get_response_headers_as_dictionary()
 	# FIXME: extract from headers "Content-Type": "application/json; charset=utf-8"
-	# This begs for a HttpResponse class ; wait for Godot?
+	# Perhaps use a method of {{>partials/api_response_class_name}} for this?
 	var encoding := "utf-8"
 	var mime := "application/json"
-	response_headers['Encoding'] = encoding
-	response_headers['Mime'] = mime
+	response.headers['Encoding'] = encoding
+	response.headers['Mime'] = mime
 
+	#response.collect_body_from_client(self._bzz_client, self._bzz_config)  # to refactor
 	# TODO: cap the size of this, perhaps?
 	var response_bytes := PackedByteArray()
 
@@ -320,10 +327,10 @@ func _bzz_do_request_text(
 			response_bytes = response_bytes + chunk
 
 	self._bzz_config.log_info("%s: RESPONSE %d (%d bytes)" % [
-		_bzz_name, response_code, response_bytes.size()
+		_bzz_name, response.code, response_bytes.size()
 	])
-	if not response_headers.is_empty():
-		self._bzz_config.log_debug("→ HEADERS: %s" % str(response_headers))
+	if not response.headers.is_empty():
+		self._bzz_config.log_debug("→ HEADERS: %s" % str(response.headers))
 
 	var response_text: String
 	if encoding == "utf-8":
@@ -337,46 +344,47 @@ func _bzz_do_request_text(
 
 	if response_text:
 		self._bzz_config.log_debug("→ BODY: \n%s" % response_text)
+		response.body = response_text
 
-	if response_code >= 500:
+	if response.code >= 500:
 		var error := {{>partials/api_error_class_name}}.new()
 		error.internal_code = ERR_PRINTER_ON_FIRE
-		error.response_code = response_code
+		error.response_code = response.code
 		error.identifier = "apibee.response.5xx"
 		error.message = "%s: request to `%s' made the server hiccup with a %d." % [
-			_bzz_name, path, response_code
+			_bzz_name, path, response.code
 		]
 		error.message += "\n%s" % [
 			_bzz_format_error_response(response_text)
 		]
 		on_failure.call(error)
 		return
-	elif response_code >= 400:
+	elif response.code >= 400:
 		var error := {{>partials/api_error_class_name}}.new()
 		error.identifier = "apibee.response.4xx"
-		error.response_code = response_code
+		error.response_code = response.code
 		error.message = "%s: request to `%s' was denied with a %d." % [
-			_bzz_name, path, response_code
+			_bzz_name, path, response.code
 		]
 		error.message += "\n%s" % [
 			_bzz_format_error_response(response_text)
 		]
 		on_failure.call(error)
 		return
-	elif response_code >= 300:
+	elif response.code >= 300:
 		var error := {{>partials/api_error_class_name}}.new()
 		error.identifier = "apibee.response.3xx"
-		error.response_code = response_code
+		error.response_code = response.code
 		error.message = "%s: request to `%s' was redirected with a %d.  We do not support redirects in that client yet." % [
-			_bzz_name, path, response_code
+			_bzz_name, path, response.code
 		]
 		on_failure.call(error)
 		return
 
 	# Should we close ?
 	#self._bzz_client.close()
 
-	on_success.call(response_text, response_code, response_headers)
+	on_success.call(response)
 
 
 func _bzz_convert_http_method(method: String) -> int:
@@ -411,7 +419,7 @@ func _bzz_escape_path_param(value: String) -> String:
 func _bzz_get_content_type(headers: Dictionary) -> String:
 	if headers.has("Content-Type"):
 		return headers["Content-Type"]
-	return BEE_PRODUCIBLE_CONTENT_TYPES[0]
+	return BZZ_PRODUCIBLE_CONTENT_TYPES[0]
 
 
 func _bzz_format_error_response(response: String) -> String:

modules/openapi-generator/src/main/resources/gdscript/README.handlebars

@@ -4,7 +4,7 @@
 {{{appDescriptionWithNewLines}}}
 {{/if}}
 
-This Godot 4 addon was automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
+This *Godot 4* addon was automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
 {{#if servers}}
 − Servers:
@@ -50,6 +50,15 @@ You can now use it anywhere in your code:
 {{/with}}
 
 
+## Customization
+
+You can [override the templates](https://openapi-generator.tech/docs/templating/).
+
+> 1. Grab templates with `openapi-generator author template -g gdscript --library gdscript`
+> 2. Hack around
+> 3. Regenerate using `--template <dir>` to target your custom templates dir
+
+
 ## Documentation for API Endpoints
 
 All URIs are relative to *{{basePath}}*

modules/openapi-generator/src/main/resources/gdscript/api.handlebars

@@ -127,7 +127,7 @@ func {{operationIdSnakeCase}}(
 	{{#if consumes}}
 	var bzz_mimes_consumable_by_server := [{{#each consumes}}'{{{mediaType}}}'{{#unless @last}}, {{/unless}}{{/each}}]
 	var bzz_found_producible_mime := false
-	for bzz_mime in BEE_PRODUCIBLE_CONTENT_TYPES:
+	for bzz_mime in BZZ_PRODUCIBLE_CONTENT_TYPES:
 		if bzz_mime in bzz_mimes_consumable_by_server:
 			bzz_headers["Content-Type"] = bzz_mime
 			bzz_found_producible_mime = true
@@ -141,7 +141,7 @@ func {{operationIdSnakeCase}}(
 	{{/if}}
 	{{#if produces}}
 	var bzz_mimes_produced_by_server := [{{#each produces}}'{{{mediaType}}}'{{#unless @last}}, {{/unless}}{{/each}}]
-	for bzz_mime in BEE_CONSUMABLE_CONTENT_TYPES:
+	for bzz_mime in BZZ_CONSUMABLE_CONTENT_TYPES:
 		if bzz_mime in bzz_mimes_produced_by_server:
 			bzz_headers["Accept"] = bzz_mime
 			break
@@ -168,18 +168,18 @@ func {{operationIdSnakeCase}}(
 	{{/each}}
 	{{/if}}
 
-	self.bzz_request(
+	self._bzz_request(
 		bzz_method, bzz_path, bzz_headers, bzz_query, bzz_body,
-		func(bzz_result, bzz_code, bzz_headers):
+		func(bzz_response):
 {{#with returnProperty}}
 	{{#if isArray}}
-			bzz_result = {{>partials/complex_type}}.bzz_denormalize_multiple(bzz_result)
+			bzz_response.data = {{>partials/complex_type}}.bzz_denormalize_multiple(bzz_response.data)
 	{{else if isModel}}
-			bzz_result = {{>partials/data_type}}.bzz_denormalize_single(bzz_result)
+			bzz_response.data = {{>partials/data_type}}.bzz_denormalize_single(bzz_response.data)
 	{{/if}}
 {{/with}}
-			on_success.call(bzz_result)
-			,  # ざわ‥
+			on_success.call(bzz_response)
+			,
 		func(bzz_error):
 			on_failure.call(bzz_error)
 			,  # ざわ‥
@@ -200,6 +200,7 @@ func {{operationIdSnakeCase}}_threaded(
 	)
 	bzz_thread.start(bzz_callable)
 	return bzz_thread
+
 {{/each}}
 
 {{/with}}

modules/openapi-generator/src/main/resources/gdscript/api_doc_example.handlebars

@@ -26,12 +26,13 @@ api.{{{operationIdSnakeCase}}}(
 {{#each allParams}}
 	# {{paramName}}{{#if dataType}}: {{dataType}}{{/if}}{{#if defaultValue}} = {{{defaultValue}}}{{/if}}{{#if example}}   Eg: {{{example}}}{{/if}}
 	# {{{description}}}
-{{!-- `example` is not available here, not sure why --}}
+	{{! `example` is not available here, not sure why }}
 	{{paramName}},
 {{/each}}
 	# On Success
-	func(result):{{#with returnProperty}}  # result is {{>partials/complex_type}}{{/with}}
-		prints("Success!", "{{operationIdSnakeCase}}", result)
+	func(response):{{#with returnProperty}}  # response is {{>partials/api_response_class_name}}{{/with}}
+		prints("Success!", "{{operationIdSnakeCase}}", response)
+		{{#with returnProperty}}assert(response.data is {{>partials/complex_type}}){{/with}}
 		pass  # do things, make stuff
 		,
 	# On Error

modules/openapi-generator/src/main/resources/gdscript/core/ApiResponse.handlebars

@@ -0,0 +1,23 @@
+extends {{>partials/api_response_parent_class}}
+class_name {{>partials/api_response_class_name}}
+
+# Headers sent back by the server
+@export var headers := Dictionary()
+
+# Raw body of this response, in String form (before deserialization)
+@export var body := ""
+
+# The HTTP response code, if any.  A constant like HTTPClient.RESPONSE_XXXX
+@export var code := 0
+
+# Deserialized body (may be pretty much any type)
+var data
+
+
+func _to_string() -> String:
+	var s := "ApiResponse"
+	if code:
+		s += " %d" % code
+	if body:
+		s += " %s" % body
+	return s