Implementing cross-platform support by supporting Linux-friendly HTTP clients #143

mergesort · 2025-05-18T20:43:41Z

This PR adds support for Linux, as requested in #89. It does so by:

Creating a new networking layer using Apple's AsyncHTTPClient library. This is considered to be the gold-standard for Swift on Linux, and is also a solid networking layer for iOS/macOS apps, and fixes the many bugs that URLSession has on Linux platforms.
To ensure compatibility on Apple platforms, I've added a URLSessionHTTPClientAdapter which makes network requests through URLSession.
When creating a new service, there is a configurable parameter for users to specify their preferred HTTPClient. This allows maximum flexibility for end-users, in case they have a preference for networking stack.

Note

These changes are not applied to any of the code related to AIProxy. I've left everything alone there as best as I can, and simply do not compile any AIProxy code on Linux, since AIProxy does not make much sense to use in a server environment where API requests are already protected.

Please let me know what you think, happy to make any changes you request. Would love to get this merged in so I can start using SwiftOpenAI in my server-side app!

gsabran

I left a few comments, mostly with the goal to not change anything on non Linux platforms other than adding a layer of indirection that is fine.

If this merges, you might want to follow up with adding some CI on Linux (maybe just build and run tests) to prevent future breakages as I don't think a lot of people would think about testing on this platform.

gsabran · 2025-05-19T04:10:46Z

Package.swift

+  dependencies: [
+    .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.25.2"),
+  ],


I'm not sure this is possible, but can we scope this to only linux for now? ie wrap in #if os(Linux) ?

I've made this change by using condition: .when(platforms: [.linux]), since #if os(Linux) doesn't work in Package.swift.

gsabran · 2025-05-19T04:12:45Z

Sources/OpenAI/AIProxy/AIProxyService.swift

+  let httpClient: HTTPClient
  let session: URLSession


I'm not super familiar with the code, but it seems weird to see both HTTPClient and URLSession properties here.

why not remove the session property, the NoOpClient type, and do

self.httpClient = URLSessionHTTPClientAdapter(urlSession: URLSession( configuration: .default, delegate: aiproxySecureDelegate, delegateQueue: nil))

This was a good idea, removed the NoOpClient in favor of your solution!

gsabran · 2025-05-19T04:18:03Z

Sources/OpenAI/Private/Networking/AsyncHTTPClientAdapter.swift

+import NIOHTTP1
+
+/// Adapter that implements HTTPClient protocol using AsyncHTTPClient
+public class AsyncHTTPClientAdapter: HTTPClient {


Maybe to reduce the scope of the change in this PR, what do you think of:

scope this code to only Linux.

replaces usages of AsyncHTTPClientAdapter.createDefault() by HTTPClient.createDefault()

add

extension HTTPClient { static func createDefault() -> HttpClient { #if os(Linux) AsyncHTTPClientAdapter.createDefault() #else URLSessionHTTPClientAdapter() #endif }

gsabran · 2025-05-19T04:21:02Z

Sources/OpenAI/Public/Service/OpenAIServiceFactory.swift

  ///   - decoder: The JSON decoder to be used for parsing API responses (default is `JSONDecoder.init()`).
+  ///   - httpClient: The HTTPClient to be used for network calls. Defaults to `AsyncHTTPClientAdapter.createDefault()`


@jamesrochabrun how do you feel about changing existing APIs here?

Would you prefer to keep the existing ones available outside of Linux, and have them map to the new ones, at the cost of having two functions that mostly do the same thing, or are you fine with the breaking change?

I think its better to have it as another initializer, I would like to avoid breaking changes if possible.

gsabran · 2025-05-19T04:26:35Z

Sources/OpenAI/Public/Service/OpenAIService.swift

+
+      // Convert URLRequest to HTTPRequest
+      let httpRequest = HTTPRequest(
+        url: request.url!,


the ! always looke scary

gsabran · 2025-05-19T04:27:13Z

Sources/OpenAI/Public/Service/OpenAIService.swift

-    guard let httpResponse = response as? HTTPURLResponse else {
-      throw APIError.requestFailed(description: "invalid response unable to get a valid HTTPURLResponse")
-    }
-    printHTTPURLResponse(httpResponse)


note: this is removed

gsabran · 2025-05-19T04:29:41Z

Sources/OpenAI/Public/Service/OpenAIService.swift

+      let httpRequest = HTTPRequest(
+        url: request.url!,
+        method: HTTPMethod(rawValue: request.httpMethod ?? "GET") ?? .get,
+        headers: request.allHTTPHeaderFields ?? [:],
+        body: request.httpBody
+      )


nit: this is repeated several times. Maybe add an initializer in HTTPRequest from URLRequest ?

mergesort · 2025-05-20T13:10:52Z

These are all great suggestions, I'll address them in the next couple of days.

I should have noted this but I had left in the AsyncHTTPClient code on iOS/macOS so changes could be tested by people on Apple platforms, but happy to contain everything AsyncHTTPClient-related to Linux only.

jamesrochabrun · 2025-05-22T06:46:08Z

Thanks @mergesort for your willingness to address @gsabran feedback!

mergesort · 2025-06-07T02:58:37Z

Sorry for the time it took, but I believe I've addressed all of the concerns. Please let me know if I've missed anything — excited to have this functionality on the server!

jamesrochabrun · 2025-06-07T05:27:26Z

@mergesort this is awesome, thanks for addressing the feedback, I will defer to @gsabran to do the final review, but can I please ask you to add a section in the Read me in how to use this new functionality? it will be nice to show it for others. Thanks!

AlekseyPleshkov · 2025-06-07T10:08:26Z

Sorry for the time it took, but I believe I've addressed all of the concerns. Please let me know if I've missed anything — excited to have this functionality on the server!

Thank you for your work! I have tried to build docker-image (vapor+swiftopenai) and faced with a lot of errors.

I found a couple of places in code where use UIKit/AppKit to work with images and build fails here:

ImageEditParameters.swift:39:8: error: cannot find 'imageData' in scope
CreateImageEditParameters.swift:104:17: error: cannot find 'maskData' in scope
other places where UIKit/AppKit importability is checked

Missing arguments error for HTTPRequest:

OpenAIService.swift:1015:40: error: missing arguments for parameters 'url', 'method', 'headers' in call
other places where HTTPRequest is created

I just wanted to highlight these places because they might be important.

mergesort · 2025-06-07T17:01:51Z

@AlekseyPleshkov I'm so sorry about that, I had been testing against my app's server, which I plan to deploy this on. I thought everything had worked on Linux, but only now did I realize that in my haste to push a new feature last week I had commented out an internal import of the package containing SwiftOpenAI, so I was seeing successful builds when they would have failed.

I've created a docker image locally for testing, and am once again trying to resolve the issues you're seeing. You may see a few pushes from me, especially as I work through adding Linux testing on CI (CI is not a strength of mine), so please excuse me if that doesn't work yet and you get a few notifications about me pushing changes.

@jamesrochabrun Yes, will absolutely add some notes to the readme before considering this done. 🙂

mergesort · 2025-06-07T18:33:21Z

I've fixed all the errors (tested both in Docker and on my server), updated the readme, and the code should be working as expected now. Please let me know if this all works for you — I think I've addressed all of the concerns but I'm happy to make any other changes as needed.

As I mentioned, I'm not great at CI, so I used Claude Code to update the ci.yml based on these prompts. (Where Pasted text 1 | 2 | 3 are the logs from previous CI failures.

All of the code seems to be good now, but I'm still having some issues with getting Github Actions
to pass. Can you take a look at our ci.yml Github Action (in `.github/workflows/ci.yml) and these
logs, to see if we can fix this? I suspect we need to run build-and-test on macOS and Linux, but
the lint phase should only run on macOS, but perhaps there's more to it. [Pasted text #1 +1637 
lines] [Pasted text #2 +63 lines] [Pasted text #3 +52 lines]

Note

There was one more correction I needed to make after that, running the linter to address all of the code style requirements. I noticed that this is a recent addition to the repo, and I thought Claude made a good suggestion, to automatically run linting as part of the PR process. While it's not something to do for this PR, I figured I'd attach the suggested auto-formatting version of the ci.yml, in case you'd like to consider that for another PR.
ci-auto-format.yml.zip

mergesort added 2 commits May 18, 2025 15:36

Preparing cross-platform support by migrating URLSession to HTTPClient

a896e09

Implementing URLSessionHTTPClientAdapter for Apple operating systems

9ca94c4

mergesort mentioned this pull request May 18, 2025

Serverside / Linux support #89

Open

gsabran reviewed May 19, 2025

View reviewed changes

Addressing feedback for keeping AsyncHTTPClient contained to Linux

fdf93d9

jamesrochabrun requested a review from gsabran June 7, 2025 05:24

mergesort added 3 commits June 7, 2025 12:19

Adding Ubuntu to CI build and test action

c9798d7

Adding more #if canImport statements for proper Linux compilation

195dd42

Fixing HTTPClient errors

6d068cd

mergesort added 3 commits June 7, 2025 13:46

Updating readme to note updated platform support

3467e61

Updating CI build and test CI commands

0274d45

Fix for formatting issues that were causing linting to fail

6a94d26

		/// - decoder: The JSON decoder to be used for parsing API responses (default is `JSONDecoder.init()`).
		/// - httpClient: The HTTPClient to be used for network calls. Defaults to `AsyncHTTPClientAdapter.createDefault()`

Implementing cross-platform support by supporting Linux-friendly HTTP clients #143

Are you sure you want to change the base?

Implementing cross-platform support by supporting Linux-friendly HTTP clients #143

Conversation

mergesort commented May 18, 2025

Uh oh!

gsabran left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mergesort commented May 20, 2025

Uh oh!

jamesrochabrun commented May 22, 2025

Uh oh!

mergesort commented Jun 7, 2025

Uh oh!

jamesrochabrun commented Jun 7, 2025

Uh oh!

AlekseyPleshkov commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergesort commented Jun 7, 2025

Uh oh!

mergesort commented Jun 7, 2025

Uh oh!

Uh oh!

AlekseyPleshkov commented Jun 7, 2025 •

edited

Loading