Skip to content

Revert streaming codable handler and provide it as an example, not an API #549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 7, 2025

Conversation

sebsto
Copy link
Contributor

@sebsto sebsto commented Aug 5, 2025

Revert streaming codable handler change and propose it as an example instead of an handler API.

Motivation:
I made a mistake when submitting this PR
#532

It provides a Streaming+Codable handler that conveniently allows developers to write handlers with Codable events for streaming functions.

This is a mistake for three reasons:

  • This is the only handler that assumes a Lamba Event structure as input. I added a minimal FunctionUrlRequest and FunctionURLResponse to avoid importing the AWS Lambda Events library. It is the first handler to be event-specific. I don't think the runtime should introduce event specific code.

  • The handler only works when Lambda functions are exposed through Function URLs. Streaming functions can also be invoke by API or CLI.

  • The handler hides FunctionURLRequest details (HTTP headers, query parameters, etc.) from developers

Developers were unaware they were trading flexibility for convenience

The lack of clear documentation about these limitations led to incorrect usage patterns and frustrated developers who needed full request control or were using other invocation methods.

Modifications:

  • Removed the Streaming+Codable API from the library
  • Moved the Streaming+Codable code to an example
  • Added prominent warning section in the example README explaining the limitations
  • Clarified when to use Streaming+Codable vs ByteBuffer approaches
  • Added decision rule framework to help developers choose the right approach

Result:
The only API provided by the library to use Streaming Lambda functions is exposing the raw ByteBuffer as input, there is no more Codable handler for Streaming functions available in the API. I kept the Streaming+Codable code an example.

After this change, developers have clear guidance on when to use each streaming approach:

  • Use streaming codable for Function URL + JSON payload + no request details needed
  • Use ByteBuffer StreamingLambdaHandler for full control, other invocation methods, or request metadata access

This prevents misuse of the API and sets proper expectations about the handler's capabilities and limitations, leading to better developer experience and fewer integration issues.

@sebsto sebsto added this to the 2.0 milestone Aug 5, 2025
@sebsto sebsto self-assigned this Aug 5, 2025
@sebsto sebsto added the ⚠️ semver/major Breaks existing public API. label Aug 5, 2025
@sebsto sebsto changed the title Revert streaming codable handler to Function URL only usage Revert streaming codable handler to Example only usage Aug 5, 2025
@sebsto sebsto marked this pull request as draft August 6, 2025 05:45
@sebsto
Copy link
Contributor Author

sebsto commented Aug 6, 2025

Simplify the Streaming+Codable adapter code when swift-server/swift-aws-lambda-events#90 will be merged

@sebsto sebsto marked this pull request as ready for review August 6, 2025 16:08
@sebsto sebsto requested a review from adam-fowler August 6, 2025 16:08
@sebsto sebsto changed the title Revert streaming codable handler to Example only usage Revert streaming codable handler and provide it as an example, not an API Aug 6, 2025
@sebsto sebsto force-pushed the sebsto/revert_streaming+codable branch from 54bb8bd to e409852 Compare August 6, 2025 16:10
@sebsto sebsto merged commit 262c3b5 into swift-server:main Aug 7, 2025
34 of 35 checks passed
@sebsto sebsto deleted the sebsto/revert_streaming+codable branch August 7, 2025 08:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
⚠️ semver/major Breaks existing public API.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants