apple / apple/swift-openapi-generator

Offer Structured Concurrency conforming APIs for response streaming

Open
#728 0 comments 1 reaction 0 assignees View on GitHub
good first issue kind/enhancement status/needs-design
Dominant language
Swift
Stars
2k
Forks
182
Avg merge
13h 28m
Merged PRs (30d)
5

Description

### Motivation

At the moment, the generator generates functions that violate Structured Concurrency for things that use 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 (#727)
2. An alternative should be offered (such as `try await withFooRequest(parameters: Parameters) { result, responseBodyStream in ... }`) [this feature request]

This feature request part (2), the _additional_ availability of a fully structured API that does response streaming.

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

### Proposed solution

Offer properly structured APIs that support HTTP response streaming in a `with*` function.

### Alternatives considered

_No response_

### Additional information

_No response_

Contributor guide

Open the contributing guide

Research direction

No implementation files or tests are named in the issue. Start by tracing the generator's existing HTTP response-streaming APIs and compare the linked Swift NIO and async-http-client efforts. Done means generated APIs offer a structured with-style response-streaming alternative while keeping acquired request resources within the operation's lifetime.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, swift
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.