Skip to content

resolves #280 allow sending custom HTTP headers when downloading UI bundle

Introduces the possibility to define custom HTTP headers in the playbook that will be send when fetching a remote UI bundle.

This specifically allows downloading UI bundles from non-public sources (by setting the authorization header with an appropriate value) or public sources with specific requirements such as the GitHub API (as highlighted in the documentation).

Additionally, a custom default user-agent has been added. Without sending a value for user-agent requests to e.g. the GitHub API will be rejected with a 403 Forbidden. Even without that requirement the Antora UI loader should be a good citizen of the internet and properly identify itself during requests.

I am aware that #280 mentioned using the GitHub JS API (probably oktokit/request), however, this comes with a huge additional implementation overhead – specifically having to deal with GitHub vs. everyone else as well as GitHub Enterprise. I opted to not pursue this after initial attempts because of the difficulty to reconcile these different sources as well as technical difficulties arising from the WILDY different NodeJS versions required by Antora and any reasonably modern version of oktokit/request.

I believe integrating the GH API to resolve relative asset URLs (e.g. latest) is a very cool thing to have, however, not as important as being able to download from GH (or any custom, private source for that matter) at all. If people need to do that they would still be able to use the GH CLI/API (e.g. in their GH Workflow) to resolve that asset URL and manipulate the playbook in-place absolving Antora of that responsibility (for now).

An additional thing concerning providing the authorization information via the URL directly: This is also something I briefly looked at, however, this would best be done by converting the UI bundle URL into a URL – that, however, also necessitates touching a lot of places concerning URL handling. Not to mention that this does not (from a short test) appear to mesh well with simple-get used to make requests. Specifically, I think it would require additional processing of the URL and transposing potential basic auth information to the headers-object. Not to mention differentiating between true basic auth and "fake" basic auth that is actually a bearer-token and encoding each correctly. It strikes me as better to simply provide users with the means to provide the correct (intended) header themselves.

It would probably be a good idea to allow users to provide these custom headers via environment or additional file (as mentioned in this comment) – I may be able to take a look at that either within this PR or as a follow-up if there is any interest in merging this solution at all.

Edited by Nikolas Grottendieck

Merge request reports