apple / apple/swift-openapi-generator
Document Structured Concurrency violating functions
- Dominant language
- Swift
- Stars
- 2k
- Forks
- 182
- Avg merge
- 13h 28m
- Merged PRs (30d)
- 5
Description
### Description
At the moment, the generator generates functions that violate Structured Concurrency, for example anything that uses HTTP _response_ streaming. The user gets returned an async sequence that they are then supposed to stream and until that's done resources in other tasks/threads are still holding onto the live request.
This is of course violates the main principle of Structured Concurrency which is that upon return of a function, the execution resources it acquired have been released back.
Violating Structured Concurrency might be acceptable in certain cases but:
1. It should be documented that what's going on [this bug report]
2. An alternative should be offered (such as `try await withFooRequest(parameters: Parameters) { result, responseBodyStream in ... }`) [#728]
This bug report is squarely about (1), the documentation that certain APIs (namely anything that does HTTP response streaming) violates Structured Concurrency.
Similar efforts in other projects:
- https://github.com/apple/swift-nio/pull/3108
- https://github.com/swift-server/async-http-client/pull/806
- https://github.com/swift-server/async-http-client/issues/807
### Reproduction
n/a
### Package version(s)
all
### Expected behavior
docs
### Environment
n/a
### Additional information
_No response_
Contributor guide
Research direction
The issue names no files or tests; start by locating the documentation for generated APIs that use HTTP response streaming and review how those APIs are described. Document that these APIs can violate Structured Concurrency by retaining request resources until the returned async sequence finishes, and verify the affected API documentation clearly states this behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100