Package io.jenkins.plugins.namespacecloud.client

Class NamespaceClient

java.lang.Object
io.jenkins.plugins.namespacecloud.client.NamespaceClient
All Implemented Interfaces:
Closeable, AutoCloseable
public final class NamespaceClient extends Object implements Closeable
Thin wrapper over the Namespace ComputeService gRPC API.

One instance owns one ManagedChannel; callers must close() it. The channel is cheap to keep open and expensive to rebuild, so the cloud holds a long-lived client rather than creating one per provisioning request.

  • Field Details

  • Constructor Details

    • NamespaceClient

      public NamespaceClient(@NonNull String computeEndpoint, @NonNull Secret token)

  • Method Details

    • computeEndpointForRegion

      public static String computeEndpointForRegion(@NonNull String region)
      ComputeService is served per-region, not globally. global.namespaceapis.com returns an nginx 404 for every compute route, so the region matters.

    • endpoint

      public String endpoint()

    • listInstanceCount

      public int listInstanceCount()
      Read-only probe used by the configuration page's "Test connection" button. Requires only instance:list, so it is safe to run from a least-privilege token and creates nothing.
      Returns:
      the number of instances currently visible to the token.

    • createInstance

      public Compute.InstanceMetadata createInstance(@NonNull Compute.CreateInstanceRequest request)
      Creates an instance. Returns immediately; the instance is not yet RUNNING.

    • waitForRunning

      public Compute.InstanceMetadata waitForRunning(@NonNull String instanceId, @NonNull Duration timeout)
      Blocks until the instance reaches RUNNING.

      Uses the unary WaitInstanceSync rather than the streaming WaitInstance: the plugin has no use for intermediate state transitions, and a unary call carries a deadline cleanly.

    • describe

      public Compute.InstanceMetadata describe(@NonNull String instanceId)

    • destroyInstance

      public void destroyInstance(@NonNull String instanceId, @NonNull String reason)
      Destroys an instance. Treats "already gone" as success.

    • listByLabel

      public List<Compute.InstanceMetadata> listByLabel(@NonNull String key, @NonNull String value)
      Lists instances carrying the given label, used to reap instances whose Jenkins-side node disappeared (controller restart, crash, manual delete).

    • sshConfig

      public Compute.GetSSHConfigResponse sshConfig(@NonNull String instanceId)
      Fetches the SSH endpoint for an instance; only used by the SSH launch strategy.

    • probePermissions

      public NamespaceClient.Permissions probePermissions()
      Establishes which instance actions the token permits, without creating anything.

      Every check but list runs against a non-existent instance id. Any status other than PERMISSION_DENIED means authorization passed, so NOT_FOUND (and even INVALID_ARGUMENT, if the id shape is rejected) both count as "granted". create cannot be probed this way and is the one action that only shows up at provisioning time.

    • listImageRefs

      public List<String> listImageRefs(int maxRepositories)
      Lists the images available in the workspace's own registry, as fully qualified references ready to be used as an agent image.

      Namespace reports a repository name; whether that already includes the workspace segment varies, so a name that already looks like a path is used as-is and a bare name is left bare. Either way the caller offers these as suggestions, not as the only permitted values.

    • listImageRefs

      public List<String> listImageRefs(int maxRepositories, String workspacePrefix)
      Parameters:
      workspacePrefix - the workspace segment of an nscr.io reference; the registry reports bare repository names, so without this the produced references are not pullable.

    • verifyWorkspacePrefix

      public NamespaceClient.PrefixCheck verifyWorkspacePrefix(@NonNull Secret token, @NonNull String prefix)
      Checks a workspace prefix by asking the registry for a repository that is known to exist.

      The gRPC registry API cannot do this: it is tenant-scoped by the token and never reports the tenant id, so a wrong prefix is indistinguishable there. The Docker registry HTTP API can, because the prefix is part of the path: nscr.io/<prefix>/<repo>.

      Deliberately returns NamespaceClient.PrefixCheck.INCONCLUSIVE rather than failing when anything is unexpected. A wrong answer here would block a correct configuration, which is worse than not checking at all.

    • toTimestamp

      public static com.google.protobuf.Timestamp toTimestamp(@NonNull Instant when)
      Converts an absolute wall-clock deadline into the protobuf type the API expects.

    • toInstant

      @Nullable public static Instant toInstant(@Nullable com.google.protobuf.Timestamp ts)

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable