Allow creating instances without waiting

[jvstme]

Add InstancesService.create_nowait method that returns immediately after sending a create request to the API.

Resolves #79

[huksley]

Good idea!

Can this be rewritten to support the same syntax as for clusters, i.e.

...instance.create(
            # Set to None to not wait for provisioning but return immediately
            wait_for_status=verda_client.constants.cluster_status.PROVISIONING
)

[jvstme]

@huksley, even with wait_for_status=None, ClustersService.create still issues two API calls: POST /clusters followed by GET /clusters/<id>. We could implement the same behavior for instances, but ideally we’d like to avoid the second request so we never end up in the following situation:

• POST /instances — success
• GET /instances/<id> — error (API error, network issue, etc.)
• Result: the instance is created and starts accumulating charges, but its ID is never returned by InstancesService.create, leaving the application unaware of its existence.

Here are a few possible ways to address this:

1. Introduce a separate InstancesService.create_nowait method that does not call GET /instances/<id> (as proposed in this PR).

2. Make the return type of InstancesService.create depend on the wait_for_status parameter:

   • If wait_for_status is set, return an Instance.
   • If wait_for_status is None, return the instance ID as str (since POST /instances only returns the ID).

   Or introduce a separate parameter to control the return type.

3. Update the REST API so POST /instances returns a full Instance object. Since this is not backward-compatible, this would require either a new API version (/v2) or an opt-in mechanism via a request parameter.

Please let me know if any of these options seem reasonable, or if you have alternative suggestions.

[huksley]

Would it be ok if instance.create() with with wait_for_status=None would return instance populated with ID and values passed as request payload? that way, no get instance method will be needed

[jvstme]

@huksley, InstancesService.create doesn't have enough details to populate all instance fields, including price_per_hour, status, created_at, cpu, gpu, memory, etc.

[jvstme]

@huksley, I’ve added the wait_for_status parameter as you initially suggested. For now, I think we can live with the extra GET /instances/<id> call. This still isn’t ideal, since instance loss remains possible, but it’s less likely than before. We’d appreciate it if this could be improved further in the future, possibly by returning the full instance object from POST /instances.

I also had to add support for callables in wait_for_status; otherwise, it wouldn’t be backward compatible with the existing behavior, which checks for status != ordered instead of waiting for a specific status.