Merge pull request #85 from swift-developer-tools/feature/stream-advanced

Add Stream (Advanced) bindings

Author: swift-developer-tools-archive

Sources/SwiftLibgit2/Config-Advanced/Config-Advanced-Structs.swift

@@ -78,7 +78,7 @@ public struct GitConfigIterator: CStruct
     /// Gets the next backend entry.
     public let next     : GitConfigIterator.Next?
 
-    /// Frees the memory allocated for the iterator.
+    /// Frees the memory allocated for the given `git_config_iterator` instance.
     public let free     : GitConfigIterator.Free?
 
 
@@ -144,37 +144,37 @@ public struct GitConfigBackend: CStruct
     /// The repository configuration.
     public let cfg          : OpaquePointer?
 
-    /// Opens the backend at the given level.
+    /// Opens the given backend at the given level.
     public let open         : GitConfigBackend.Open?
 
-    /// Gets the specified configuration entry from the backend.
+    /// Gets the specified configuration entry from the given backend.
     public let get          : GitConfigBackend.Get?
 
-    /// Sets a configuration entry in the backend.
+    /// Sets a configuration entry in the given backend.
     public let set          : GitConfigBackend.Set?
 
-    /// Sets a multivar entry in the backend.
+    /// Sets a multivar entry in the given backend.
     public let setMultivar  : GitConfigBackend.SetMultivar?
 
-    /// Deletes the specified configuration entry from the backend.
+    /// Deletes the specified configuration entry from the given backend.
     public let del          : GitConfigBackend.Del?
 
-    /// Deletes the specified multivar entry from the backend.
+    /// Deletes the specified multivar entry from the given backend.
     public let delMultivar  : GitConfigBackend.DelMultivar?
 
-    /// Creates an iterator for the backend.
+    /// Creates an iterator for the given backend.
     public let iterator     : GitConfigBackend.Iterator?
 
-    /// Creates a read-only snapshot of the backend.
+    /// Creates a read-only snapshot of the given backend.
     public let snapshot     : GitConfigBackend.Snapshot?
 
-    /// Locks the backend.
+    /// Locks the given backend.
     public let lock         : GitConfigBackend.Lock?
 
-    /// Unlocks the backend.
+    /// Unlocks the given backend.
     public let unlock       : GitConfigBackend.Unlock?
 
-    /// Frees the memory allocated for the backend.
+    /// Frees the memory allocated for the given backend.
     public let free         : GitConfigBackend.Free?
 
 

Sources/SwiftLibgit2/ODB-Backend/ODB-Backend-Structs.swift

@@ -171,13 +171,13 @@ public struct GitODBStream: CStruct
     public let receivedBytes    : GitObjectSizeT
 
     /// Writes at most the specified number of bytes into the given buffer,
-    /// and advances the stream.
+    /// and advances the given stream.
     public let read             : GitODBStream.Read?
 
     /// Writes the specified number of bytes into the given buffer.
     public let write            : GitODBStream.Write?
 
-    /// Stores the contents of the stream as an object with the given ID.
+    /// Stores the contents of the given stream as an object with the given ID.
     ///
     /// ## Discussion
     ///
@@ -290,10 +290,10 @@ public struct GitODBWritePack: CStruct
     /// The object database backend.
     public let backend  : UnsafeMutablePointer<git_odb_backend>
 
-    /// Appends data to the packfile.
+    /// Appends the given data to the given packfile.
     public let append   : GitODBWritePack.Append?
 
-    /// Commits the packfile to the object database.
+    /// Commits the given packfile to the given object database.
     public let commit   : GitODBWritePack.Commit?
 
     /// Frees the memory allocated for the given `git_odb_writepack` instance.

Sources/SwiftLibgit2/RefDB-Backend-Advanced/RefDB-Backend-Structs.swift

@@ -23,7 +23,6 @@ import CLibgit2
 /// [`git_reference_iterator`](https://libgit2.org/docs/reference/main/sys/refdb_backend/git_reference_iterator.html)
 public struct GitReferenceIterator: CStruct
 {
-
     /// The reference database. The underlying type must be `git_refdb`.
     public let db       : OpaquePointer?
 
@@ -106,7 +105,7 @@ public struct GitReferenceIterator: CStruct
 /// ## C Equivalent
 ///
 /// [`git_refdb_backend`](https://libgit2.org/docs/reference/main/sys/refdb_backend/git_refdb_backend.html)
-public struct GitRefDBBackend: CStruct
+public struct GitRefDBBackend: CStruct, Sendable
 {
 
     /// The struct version.

Sources/SwiftLibgit2/Stream-Advanced/Stream-Advanced-Callbacks.swift

@@ -0,0 +1,34 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the swift-libgit2 open source project.
+//
+// Copyright (c) Margins Technologies LLC.
+// Licensed under the Apache License, Version 2.0.
+//
+//===----------------------------------------------------------------------===//
+
+import CLibgit2
+
+
+
+/// The callback invoked to create a new connection to the given host and port.
+/// - Parameters:
+///   - out: The pointer in which to store the stream.
+///   - host: The name of the host to which to connect the stream.
+///   - port: The port to which to connect the stream.
+/// - Returns: `0` on success, or an error code.
+///
+/// ## Discussion
+///
+/// - Warning: This is deprecated in libgit2 and will be removed in the next
+/// major release. Use ``GitStreamRegistration/Initialize`` instead.
+///
+/// ## C Equivalent
+///
+/// [`git_stream_cb()`](https://libgit2.org/docs/reference/main/sys/stream/git_stream_cb.html)
+public typealias GitStreamCB = @convention(c)
+(
+    UnsafeMutablePointer<UnsafeMutablePointer<git_stream>?>?,
+    UnsafePointer<CChar>?,
+    UnsafePointer<CChar>?
+) -> Int32

Sources/SwiftLibgit2/Stream-Advanced/Stream-Advanced-Enums.swift

@@ -0,0 +1,56 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the swift-libgit2 open source project.
+//
+// Copyright (c) Margins Technologies LLC.
+// Licensed under the Apache License, Version 2.0.
+//
+//===----------------------------------------------------------------------===//
+
+import CLibgit2
+
+
+
+/// The type of stream.
+///
+/// ## C Equivalent
+///
+/// [`git_stream_t`](https://libgit2.org/docs/reference/main/sys/stream/git_stream_t.html)
+public enum GitStreamT: UInt32, CEnum
+{
+    /// A standard non-TLS socket.
+    case gitStreamStandard  = 1
+    
+    /// A TLS-encrypted socket.
+    case gitStreamTLS       = 2
+    
+    
+    
+    /// Initializes a ``GitStreamT`` instance from the given  `git_stream_t`
+    /// instance.
+    /// - Parameter stream: The `git_stream_t` instance to use.
+    internal init?(
+        cValue stream: git_stream_t
+    )
+    {
+        switch stream
+        {
+            case GIT_STREAM_STANDARD    : self = .gitStreamStandard
+            case GIT_STREAM_TLS         : self = .gitStreamTLS
+            default                     : return nil
+        }
+    }
+    
+    
+    
+    /// Converts the ``GitStreamT`` instance into a `git_stream_t` instance.
+    /// - Returns: The `git_stream_t` instance.
+    internal func cValue() -> git_stream_t
+    {
+        switch self
+        {
+            case .gitStreamStandard : return GIT_STREAM_STANDARD
+            case .gitStreamTLS      : return GIT_STREAM_TLS
+        }
+    }
+}

Sources/SwiftLibgit2/Stream-Advanced/Stream-Advanced-Functions.swift

@@ -0,0 +1,68 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the swift-libgit2 open source project.
+//
+// Copyright (c) Margins Technologies LLC.
+// Licensed under the Apache License, Version 2.0.
+//
+//===----------------------------------------------------------------------===//
+
+import CLibgit2
+
+
+
+/// Registers the specified stream constructor.
+/// - Parameters:
+///   - type: The type of stream to register.
+///   - registration: The stream registration information to use. Pass `nil`
+///   to unregister the stream and use the system defaults.
+/// - Returns: A ``GitErrorCode`` instance.
+///
+/// ## Discussion
+///
+/// If the specified stream constructor has already been registered, it will
+/// be overwritten.
+///
+/// ## C Equivalent
+///
+/// [`git_stream_register()`](https://libgit2.org/docs/reference/main/sys/stream/git_stream_register.html)
+public func gitStreamRegister(
+    type            : GitStreamT,
+    registration    : UnsafeMutablePointer<git_stream_registration>?
+) -> GitErrorCode
+{
+    return withCConversion
+    {
+        return git_stream_register(
+            type.cValue(),
+            registration
+        )
+    }
+}
+
+
+
+/// Registers a TLS stream constructor.
+/// - Parameter ctor: The ``GitStreamCB`` callback to invoke to create a new
+/// connection. Pass `nil` to unregister the stream and use the system defaults.
+/// - Returns: A ``GitErrorCode`` instance.
+///
+/// ## Discussion
+///
+/// - Note: This function does not support HTTP CONNECT proxies.
+///
+/// - Warning: This is deprecated in libgit2 and will be removed in the next
+/// major release. Use ``GitStreamRegistration/Initialize`` instead.
+///
+/// ## C Equivalent
+///
+/// [`git_stream_register_tls()`](https://libgit2.org/docs/reference/main/sys/stream/git_stream_register_tls.html)
+public func gitStreamRegisterTLS(
+    ctor: GitStreamCB?
+) -> GitErrorCode
+{
+    return withCConversion
+    {
+        return git_stream_register_tls(ctor)
+    }
+}

Sources/SwiftLibgit2/Stream-Advanced/Stream-Advanced-Macros.swift

@@ -0,0 +1,15 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the swift-libgit2 open source project.
+//
+// Copyright (c) Margins Technologies LLC.
+// Licensed under the Apache License, Version 2.0.
+//
+//===----------------------------------------------------------------------===//
+
+/// The current version for ``GitStream``.
+///
+/// ## C Equivalent
+///
+/// [`GIT_STREAM_VERSION`](https://libgit2.org/docs/reference/main/sys/stream/GIT_STREAM_VERSION.html)
+public let gitStreamVersion: Int32 = 1