feat: Add option to pass external contexts into Go SDK's HTTP calls #1475
Conversation
Go Tests 6 files 6 suites 3m 35s ⏱️ Results for commit 81ac004. ♻️ This comment has been updated with latest results. |
APIX Tests0 tests 0 ✅ 0s ⏱️ Results for commit 57fe967. |
Python Tests 9 files 9 suites 1m 17s ⏱️ Results for commit 57fe967. |
Codegen Tests418 tests 400 ✅ 1m 6s ⏱️ Results for commit 57fe967. |
Typescript Tests 10 files 64 suites 5m 49s ⏱️ Results for commit 57fe967. |
JCPistell
force-pushed
the
go_sdk_context
branch
from
57fe967 to
1154ed8
Compare
| if s.Config.Timeout != 0 { | ||
| timeoutInSeconds = s.Config.Timeout | ||
| } | ||
| if options != nil && options.Timeout != 0 { | ||
| timeoutInSeconds = options.Timeout | ||
| } | ||
|
|
||
| ctx, cncl := context.WithTimeout(context.Background(), time.Second*time.Duration(timeoutInSeconds)) | ||
| ctx, cncl := context.WithTimeout(parent, time.Second*time.Duration(timeoutInSeconds)) |
There was a problem hiding this comment.
If the parent context has a different timeout, what's the expected behavior here? Does it go with the shorter one?
There was a problem hiding this comment.
Not exactly. If the parent hits its cancellation condition (e.g. a timeout) first then the cancellation propagates to the child.
However, If the child cancels first, it depends on how that specific error is handled... perhaps the request retries, perhaps the error is passed to the calling function, in which case most of the time the function fails and the parent context then cancels, which propagates the cancellation to all other goroutines, etc etc.
Basically this approach means you can have an overall timeout set by a parent, but each individual request running in a goroutine can also have its own timeout... this avoids the scenario where you set a 60min overall timeout, but one bad request has to wait the entire 60m to time out and fail.
| if s.Config.Timeout != 0 { | ||
| timeoutInSeconds = s.Config.Timeout | ||
| } | ||
| if options != nil && options.Timeout != 0 { | ||
| timeoutInSeconds = options.Timeout | ||
| } | ||
|
|
||
| ctx, cncl := context.WithTimeout(context.Background(), time.Second*time.Duration(timeoutInSeconds)) | ||
| ctx, cncl := context.WithTimeout(parent, time.Second*time.Duration(timeoutInSeconds)) |
There was a problem hiding this comment.
I think an easier to understand behavior would be:
If you use config's context or option's context, the timeout defined in options and config is ignored.
Trying to document/understad the how timeout works with context/config/options is confusing and harder to test. Plus if dev is using contexts, they are a power user who has way more levers to pull, and should know about using timeouts in contexts.
There was a problem hiding this comment.
I disagree - see my previous comment. I actually think this is easier to document and the tests are already in place.
|
|
||
| #### Custom Context per request | ||
|
|
||
| Follow the example here to set a context for a specific request. |
There was a problem hiding this comment.
Also add "For the specific request, the custom context will replace the custom context set for all requests in the previous "Custom Context for all requests" section."
| } | ||
| ``` | ||
|
|
||
| > Note: Setting a context per request will NOT affect the context used for the background token fetching requests. If you have also set a context for all requests as mentioned above then that context |
There was a problem hiding this comment.
Also add "If you set a custom context for a specific request, the SDK will ignore any timeout described in the previous Timeout section for the specific request. You must set the timeout with the custom context for the specific request."
There was a problem hiding this comment.
This isn't true - request timeouts will still apply - any specified context simply becomes the parent of the timeout request.
|
|
||
| If you want even greater control over the lifecycle of the HTTP requests consider providing a [context](https://pkg.go.dev/context). Contexts can be set for all requests or per request. They can be combined with the timeout options mentioned in the previous section to fine-tune the lifecycle of your requests. | ||
|
|
||
| If you wish to include timeout functionality in your custom context then you should leverage [context.WithTimeout](https://pkg.go.dev/context#WithTimeout). |
There was a problem hiding this comment.
Change to:
The SDK will ignore any timeout described in the previous Timeout section for all requests if you use custom context for all requests, or per request if you use custom context per request.
You must use [context.WithTimeout](https://pkg.go.dev/context#WithTimeout) functionality to set a timeout.
There was a problem hiding this comment.
See my previous comment - this is inaccurate.
|
|
||
| If you wish to include timeout functionality in your custom context then you should leverage [context.WithTimeout](https://pkg.go.dev/context#WithTimeout). | ||
|
|
||
| > Note: Custom contexts will be used as the parent context for any timeout you set as specified in the previous section. If the parent context gets cancelled it will propagate to the child context, but if the timeout context times out it does not propagate to the parent context. |
There was a problem hiding this comment.
Not sure what this means? Can we remove this if we're going with the new behavior?
| @@ -118,3 +118,57 @@ func main() { | |||
| } | |||
| } | |||
| ``` | |||
| ### Custom Context | |||
|
|
|||
| If you want even greater control over the lifecycle of the HTTP requests consider providing a [context](https://pkg.go.dev/context). Contexts can be set for all requests or per request. They can be combined with the timeout options mentioned in the previous section to fine-tune the lifecycle of your requests. | |||
There was a problem hiding this comment.
Change to:
You can set a [context](https://pkg.go.dev/context) for all requests or a specific request for more control over the SDK's HTTP requests.
| } | ||
| ``` | ||
|
|
||
| > Note: A context set here will become the parent context for all API calls as well as all requests to fetch/refresh oauth tokens, which are normally completely isolated from contexts set via the Timeout property. In this case the token refresh requests and each individual API call will share a common parent context. |
There was a problem hiding this comment.
Change to
Note: The SDK will ignore any timeout described in the previous Timeout section if you use custom context for all requests. You must set the timeout with the custom context.
Note: The context set here will become the parent context for all requests including the SDK's background oauth token requests. If you want to control the timeout of the SDK's background oauth token requests, you must set a custom context (with a timeout) for all requests.```
|
|
||
| Follow the example here to set a context for a specific request. | ||
|
|
||
| > Note: This will be used as the parent context for any timeout setting you've specified for API calls. If you've set contexts in both your API config and in the request options the request options context will be used instead. Background requests to fetch/refresh oauth tokens will NOT use a context set via request options - it will default to use a generic background context or, if you've also set a context in the API config it will still use that as specified in the previous section. |
| } | ||
| ``` | ||
|
|
||
| > Note: Setting a context per request will NOT affect the context used for the background token fetching requests. If you have also set a context for all requests as mentioned above then that context |
There was a problem hiding this comment.
Replace with
Note: If you set a custom context for a specific request, the SDK will ignore any timeout described in the previous Timeout section for the specific request. You must set the timeout with the request's custom context.
Note:
The custom context per request does NOT affect the background oauth token requests' context. You must use a custom context set on all requests to do so.
|
@JCPistell has this been superseded? Can we close it? |
This adds the option to include an external context in the Go SDK's HTTP calls. This is useful if the SDK is being used as part of a larger application that needs to share a context across multiple API boundaries.