apple / apple/swift-openapi-generator

Document Structured Concurrency violating functions

Open
#727 0 comments 0 reactions 0 assignees View on GitHub
area/documentation kind/enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.