fix: show a working save_record override for HTTP resources (#659)

* fix: show a working save_record override for HTTP resources

The example built its request from a fictional client and a relative path.
Copied as written that request has no host — HTTParty hands it to Net::HTTP,
which fails on a nil address (AVO-1745, seen in production on avodemo). It now
builds from the resource's own endpoint and evaluates its headers, and both
pages state that the endpoint must be absolute.

Also documents that headers reach create/update/destroy, which they now do.

* Bound the example's hand-rolled request with a timeout

* Encode the example's id like the client does

Author: adrianthedev

docs/4.0/http-resource-api.md

@@ -51,6 +51,10 @@ self.http_adapter = {
 Unlike the other adapter options, `endpoint` is used verbatim — it does not accept a proc and is not evaluated through `Avo::ExecutionContext`.
 :::
 
+:::warning Must be absolute
+The endpoint needs a host. A missing, blank, or relative value (`nil`, `""`, `"/users"`) raises [`Avo::HttpError`](./http-resource.html#handle-api-errors) before any request is sent, so the controller shows a flash message instead of failing inside `Net::HTTP` on a nil address.
+:::
+
 :::info Request behavior
 Index requests always carry `page` and `per_page` query parameters — the names are not configurable. Use [`query_params`](#query_params) to send additional parameters. Requests time out after 10 seconds and raise an error.
 :::

docs/4.0/http-resource.md

@@ -87,6 +87,8 @@ self.http_adapter = {
 
 If the headers must be computed at request time — rotating tokens, per-user credentials — pass a proc returning the hash instead.
 
+Every request carries them: index, show, and count, as well as the create, update, and destroy requests the controller makes.
+
 ## Map sorting and filtering to query params
 
 If you want Avo's sorting UI (or any UI state) forwarded to the API, build the query string with [`query_params`](./http-resource-api.html#query_params). The proc has access to controller `params`, and its result is merged into the request's query string:
@@ -136,7 +138,7 @@ The controller rescues the exception and displays the message as a flash error i
 
 ## Customize create, update, and destroy
 
-Out of the box, the HTTP controller persists changes through the resource's client — `POST` to the endpoint on create, `PATCH` to `endpoint/:id` on update, and `DELETE` to `endpoint/:id` on destroy. The default implementation looks like this:
+Out of the box, the HTTP controller persists changes through the resource's client — `POST` to the endpoint on create, `PATCH` to `endpoint/:id` on update, and `DELETE` to `endpoint/:id` on destroy, each carrying the resource's [`headers`](#send-authentication-headers). The default implementation looks like this:
 
 ```ruby
 def save_record
@@ -162,21 +164,32 @@ If your API needs different paths, extra parameters, or conditional logic, overr
 # app/controllers/avo/authors_controller.rb
 class Avo::AuthorsController < Avo::Core::Controllers::Http
   def save_record
-    auth_headers = {
-      "Authorization" => "Bearer #{ENV.fetch("API_KEY")}"
-    }
-
+    # Build the URL from the resource's own endpoint, and evaluate its headers
+    # the same way the client does — `headers` may be a proc.
+    endpoint = resource.endpoint
+    headers = Avo::ExecutionContext.new(target: resource.headers).handle
+    body = { author: @record.as_json }
+
+    # HTTParty has no default timeout — the client sets one on its own class, so
+    # a hand-rolled request has to bound itself.
     response = if action_name == "create"
-      MyCustomApi.post("/authors", body: @record.as_json, headers: auth_headers)
+      HTTParty.post(endpoint, body: body, headers: headers, timeout: 10)
     else
-      MyCustomApi.patch("/authors/#{@record.id}", body: @record.as_json, headers: auth_headers)
+      # `to_param` + encoding, like the client: a raw id breaks the moment a
+      # resource obfuscates it (see `model_class_eval`) or it contains a
+      # reserved character.
+      HTTParty.patch("#{endpoint}/#{ERB::Util.url_encode(@record.to_param)}", body: body, headers: headers, timeout: 10)
     end
 
     response.success?
   end
 end
 ```
 
+:::warning Request an absolute URL
+Avo configures no `base_uri`, so a relative path — `HTTParty.post("/authors", ...)` — has no host to connect to and fails inside `Net::HTTP` on a nil address, long after the form was submitted. Always request the resource's full `endpoint`.
+:::
+
 ## Debug console
 
 HTTP Resources ship with an interactive debug console for inspecting exactly what your resource sends and receives. Visit `<avo_root>/http-resource/debug` (e.g. `/avo/http-resource/debug`), pick a resource and an action (`index`, `show`, `count`, `create`, `update`, or `delete`), and fire the request.