Extend job launches with Git revision, access modes (#154)

* feat: support expose in package jobs

* wip support for public, dns

* try adding batchimages

* fix

* support for revision

* Exposing port on batchjob (#158)

* fix: adjust tests to new .jobaccess field

* docs: document the new remote-access and revision types

Adds docstrings for JobAccessMode, JobRemoteAccess, PackageAppRevision,
LatestRelease, Branch, and GitRevision, and includes them in the reference
manual (required by Documenter's checkdocs=:all). Also redacts the password
in JobAccessMode.Password's printed representation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor: share the JobRemoteAccess submission argument mapping

Extracts _jobaccess_auth_args and _jobaccess_submit_args, used by the batch,
package, and application job submission paths. This also fixes package jobs
crashing with a MethodError when submitted with the (unsupported) Password or
LoggedInUsers access modes: all paths now throw an InvalidRequestError that
does not leak the password into the error message.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: extract interactive product resolution for port-exposing jobs

The batch path now resolves the interactive product via a helper, fixing a
latent FieldError on its error path (BatchImage has .product, not
.product_name). Package (userapp) jobs intentionally keep the hardcoded
'package-interactive' product, now documented with a comment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: implement Password and LoggedInUsers access modes

Maps all four JobAccessMode variants to the backend's legacy appArgs
encoding (normalized by translate_auth_args! server-side). Also makes the
default LatestRelease revision omit branch_name from the submission instead
of sending an empty string, matching the wire format of older clients.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: cover JobRemoteAccess, access modes, and PackageJob revisions

Adds unit tests for the access-mode appArgs encodings (incl. password
redaction in printing), _jobaccess_submit_args, interactive product
resolution, and the revision argument mapping; exercises
expose=JobRemoteAccess end-to-end against the mocked backend. Also adds the
new public types to the public API allowlist.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: document JobRemoteAccess in submit_job, PackageJob, and the guide

Documents the expose kwarg's JobRemoteAccess option (incl. the port-only
default of JustMe + random DNS prefix), the new PackageJob image/revision
kwargs, adds a guide example and changelog entries, and fixes a module-
docstring cross-reference that broke the Documenter build.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: format files

---------

Co-authored-by: Sebastian Pfitzner <pfitzseb@gmail.com>
Co-authored-by: Criston Hyett <cmhyett@gmail.com>
Co-authored-by: Sebastian Pfitzner <sebastian@juliahub.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 4 people

CHANGELOG.md

@@ -4,6 +4,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+### Added
+
+* The `expose` argument of `submit_job` now also accepts a `JuliaHub.JobRemoteAccess` object, which additionally allows configuring who can access the exposed port (`JuliaHub.JobAccessMode`) and a fixed DNS prefix for the job. Ports can now also be exposed on package application jobs. ([#154], [#158])
+* `JuliaHub.PackageJob` now supports overriding the job image (`image`) and selecting which revision of the application to launch (`revision`, see `JuliaHub.PackageAppRevision`). ([#154])
+
 ### Fixed
 
 * Fix a `MethodError` when calling `JuliaHub.Experimental.registries`. ([#132])
@@ -240,3 +245,5 @@ Initial package release.
 [#132]: https://github.com/JuliaComputing/JuliaHub.jl/issues/132
 [#133]: https://github.com/JuliaComputing/JuliaHub.jl/issues/133
 [#149]: https://github.com/JuliaComputing/JuliaHub.jl/issues/149
+[#154]: https://github.com/JuliaComputing/JuliaHub.jl/issues/154
+[#158]: https://github.com/JuliaComputing/JuliaHub.jl/issues/158

docs/src/guides/jobs.md

@@ -265,6 +265,21 @@ job = JuliaHub.submit_job(
 )
 ```
 
+By default, only the user who submitted the job can access the exposed port, after authenticating.
+To control who can access the port, or to expose the job under a fixed DNS prefix, a
+[`JuliaHub.JobRemoteAccess`](@ref) object can be passed via `expose` instead of a plain port number:
+
+```julia
+JuliaHub.submit_job(
+    JuliaHub.script"...",
+    expose = JuliaHub.JobRemoteAccess(
+        8080;
+        mode = JuliaHub.JobAccessMode.TotallyPublic(),
+        dns_prefix = "myapp",
+    ),
+)
+```
+
 Note that, unlike a usual batch job, this job has a `.hostname` property, that will point to the DNS hostname that can be used to access the server exposed by the job (see also [the relevant reference section](@ref jobs-apis-expose-ports)).
 
 Once the job has started and the Oxygen-based server has started serving the page, you can perform [HTTP.jl](https://juliahub.com/ui/Packages/General/HTTP) requests against the job with the [`JuliaHub.request`](@ref) function, which is thin wrapper around the `HTTP.request` function that sets up the necessary authentication headers and constructs the full URL.

docs/src/reference/job-submission.md

@@ -269,6 +269,8 @@ submit_job
 Limit
 Unlimited
 WorkloadConfig
+JobRemoteAccess
+JobAccessMode
 ```
 
 ## Experimental APIs
@@ -287,6 +289,10 @@ PackageApp
 UserApp
 ApplicationJob
 PackageJob
+PackageAppRevision
+LatestRelease
+Branch
+GitRevision
 ```
 
 ## Index