Skip to content

Commit 66ff9ee

Browse files
flexlixrupflexlixrup
committed
docs: Extend documentation
1 parent dfb5151 commit 66ff9ee

8 files changed

+179
-33
lines changed

‎Sources/Pulsar/Documentation.docc/HowToUse.md

+85-12
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
# Get started
1+
# Get Started
22

3-
This section provides an overview how to quickly get the library up and running.
3+
Welcome to the Swift Pulsar Client! This guide will help you get started with the library quickly by walking you through the basic setup and usage for both consuming and producing messages.
44

5-
## Consumer
5+
## Consumer Example
6+
The following example demonstrates how to create a Pulsar consumer to receive messages from a specific topic.
67

78
```swift
89
import Logging
@@ -12,43 +13,115 @@ import Pulsar
1213
@main
1314
struct PulsarExample {
1415
static func main() async throws {
15-
// You do not need to provide your own EventLoopGroup.
16+
// Set up logging and event loop group
1617
let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount)
1718
LoggingSystem.bootstrap { label in
1819
var handler = StreamLogHandler.standardOutput(label: label)
1920
handler.logLevel = .trace
2021
return handler
2122
}
23+
2224
let connector = PulsarExample()
2325
try await connector.connect(eventLoopGroup: eventLoopGroup)
2426
}
2527

2628
func connect(eventLoopGroup: EventLoopGroup) async throws {
2729
var msgCount = 0
28-
// Create a Pulsar client and connect to the server at localhost:6650.
30+
31+
// Create a Pulsar client
2932
let client = await PulsarClient(host: "localhost", port: 6650)
3033

31-
// Create a consumer at the specified topic with the wanted subscription name.
32-
let consumer = try await client.consumer(topic: "persistent://public/default/my-topic", subscription: "test", subscriptionType: .shared)
34+
// Set up a consumer
35+
let consumer = try await client.consumer(
36+
topic: "persistent://public/default/my-topic",
37+
subscription: "test",
38+
subscriptionType: .shared
39+
)
40+
41+
// Consume messages
3342
Task {
3443
do {
35-
// Consume messages and do a thing, everytime you receive a message.
3644
for try await message in consumer {
3745
msgCount += 1
38-
print("Received message in the exec: \(String(decoding: message.data, as: UTF8.self))")
46+
print("Received message: \(String(decoding: message.data, as: UTF8.self))")
3947
if msgCount == 2 {
4048
try await consumer.close()
4149
print("Closed consumer")
4250
}
4351
}
4452
} catch {
45-
// The consumer should never close automatically, only when you call consumer.close()
46-
print("Whooops we closed, this should never happen automatically.")
53+
print("Unexpected consumer closure: \(error)")
54+
}
55+
}
56+
57+
// Keep the application running
58+
let keepAlivePromise = eventLoopGroup.next().makePromise(of: Void.self)
59+
try await keepAlivePromise.futureResult.get()
60+
}
61+
}
62+
```
63+
64+
## Producer Example
65+
This example shows how to create a producer to send messages to a specific Pulsar topic.
66+
67+
```swift
68+
import Foundation
69+
import Logging
70+
import NIO
71+
import Pulsar
72+
73+
@main
74+
struct PulsarExample {
75+
static func main() async throws {
76+
// Set up logging and event loop group
77+
let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount)
78+
LoggingSystem.bootstrap { label in
79+
var handler = StreamLogHandler.standardOutput(label: label)
80+
handler.logLevel = .trace
81+
return handler
82+
}
83+
84+
let connector = PulsarExample()
85+
try await connector.connect(eventLoopGroup: eventLoopGroup)
86+
}
87+
88+
func connect(eventLoopGroup: EventLoopGroup) async throws {
89+
let client = await PulsarClient(host: "localhost", port: 6650, reconnectLimit: 10) { error in
90+
print("Client closed due to error: \(error)")
91+
exit(0)
92+
}
93+
94+
// Set up a producer
95+
let producer = try await client.producer(
96+
topic: "persistent://public/default/my-topic1",
97+
accessMode: .shared,
98+
schema: .string
99+
) { _ in
100+
print("Producer closed")
101+
} as PulsarProducer<String>
102+
103+
// Send messages in a loop
104+
Task {
105+
while true {
106+
do {
107+
let message = "Hello from Swift"
108+
try await producer.asyncSend(message: Message(payload: message))
109+
print("Sent message: \(message)")
110+
try await Task.sleep(for: .seconds(5))
111+
} catch {
112+
print("Failed to send message: \(error)")
113+
}
47114
}
48115
}
49-
// Keep the application running.
116+
117+
// Keep the application running
50118
let keepAlivePromise = eventLoopGroup.next().makePromise(of: Void.self)
51119
try await keepAlivePromise.futureResult.get()
52120
}
53121
}
54122
```
123+
124+
## Additional Features
125+
- **Reconnection Handling**: Configure the reconnection limit with the `reconnectLimit` parameter when initializing the `PulsarClient`.
126+
- **Schema Support**: Specify schemas like `.string` for type-safe message handling.
127+
- **Logging**: Use Swift's `Logging` package to customize log levels and outputs.

‎Sources/Pulsar/Documentation.docc/SupportedFeatures.md

+74-4
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,80 @@
22

33
The library is not (yet) complete. This section provides an overview of the supported features of the library.
44

5-
## Client
5+
## Client Features
66

7-
## Consumer
7+
| Feature | Supported | Notes |
8+
|---------------------------------|-----------|-----------------------------------------------|
9+
| **Authentication** | | |
10+
| - Token-based Authentication | No | |
11+
| - TLS Authentication | No | |
12+
| - OAuth2 Authentication | No | |
13+
| **Encryption** | | |
14+
| - End-to-End Encryption | No | |
15+
| **Connection Handling** | | |
16+
| - Automatic Reconnection | Yes | |
17+
| - Connection Timeout Config | No | |
18+
| **Logging and Metrics** | | |
19+
| - Built-in Logging | Yes | |
20+
| - Metrics Collection | No | |
821

9-
## Producer
22+
## Producer Features
1023

11-
## Reader
24+
| Feature | Supported | Notes |
25+
|---------------------------------|-----------|-----------------------------------------------|
26+
| **Message Routing** | | |
27+
| - Key-based Routing | No | |
28+
| - Custom Partitioning | No | |
29+
| **Message Delivery** | | |
30+
| - Synchronous Send | Yes | |
31+
| - Asynchronous Send | Yes | |
32+
| - Batch Message Publishing | No | |
33+
| **Compression** | | |
34+
| - LZ4 Compression | No | |
35+
| - ZLIB Compression | No | |
36+
| - ZSTD Compression | No | |
37+
| - SNAPPY Compression | No | |
38+
| **Message TTL** | | |
39+
| - Set per Message | No | |
40+
| **Delayed Delivery** | | |
41+
| - Deliver After Delay | No | |
42+
| - Deliver at Specific Time | No | |
43+
44+
## Consumer Features
45+
46+
| Feature | Supported | Notes |
47+
|---------------------------------|-----------|-----------------------------------------------|
48+
| **Subscription Types** | | |
49+
| - Exclusive | Yes | |
50+
| - Shared | Yes | |
51+
| - Failover | Yes | |
52+
| - Key_Shared | Yes | |
53+
| **Message Acknowledgment** | | |
54+
| - Individual Acknowledgment | Yes | |
55+
| - Cumulative Acknowledgment | No | |
56+
| - Negative Acknowledgment | No | |
57+
| **Batch Message Consumption** | | |
58+
| - Batch Receive | No | |
59+
| **Dead Letter Policy** | | |
60+
| - Dead Letter Topic Support | No | |
61+
| **Message Redelivery** | | |
62+
| - Delayed Redelivery | No | |
63+
| - Max Redelivery Attempts | No | |
64+
65+
## Reader Features (Not implemented)
66+
67+
| Feature | Supported | Notes |
68+
|---------------------------------|-----------|-----------------------------------------------|
69+
| **Message Reading** | | |
70+
| - Start from Specific MessageID | No | |
71+
| - Start from Timestamp | No | |
72+
| **Non-Durable Subscriptions** | | |
73+
| - Ephemeral Readers | No | |
74+
75+
## TableView Features (Not implemented)
76+
77+
| Feature | Supported | Notes |
78+
|---------------------------------|-----------|-----------------------------------------------|
79+
| **Key-Value Access** | | |
80+
| - Real-time Key-Value Updates | No | |
81+
| - Snapshot of Latest Key-Values | No | |

‎Sources/Pulsar/Protos.swift

-14
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,3 @@
1-
// Copyright 2025 Felix Ruppert
2-
//
3-
// Licensed under the Apache License, Version 2.0 (the License );
4-
// you may not use this file except in compliance with the License.
5-
// You may obtain a copy of the License at
6-
//
7-
// http://www.apache.org/licenses/LICENSE-2.0
8-
//
9-
// Unless required by applicable law or agreed to in writing, software
10-
// distributed under the License is distributed on an AS IS BASIS,
11-
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12-
// See the License for the specific language governing permissions and
13-
// limitations under the License.
14-
151
// DO NOT EDIT.
162
// swift-format-ignore-file
173
// swiftlint:disable all

‎Sources/Pulsar/PulsarClient/PulsarClient.swift

+8-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,14 @@ import Logging
1616
import NIO
1717
@_exported import SchemaTypes
1818

19-
/// The core Pulsar Client used to connect to the server. All control of the library, like consumers and producers and its settings are controlled via the Client.
19+
/// The core Pulsar Client used to connect to the server.
20+
///
21+
/// This actor manages the connection to a Pulsar server and provides functionality
22+
/// for creating and managing producers and consumers. It also handles configuration
23+
/// of connection parameters and retry mechanisms.
24+
///
25+
/// All interactions with the Pulsar messaging system, such as sending or receiving messages,
26+
/// are controlled through this client.
2027
public final actor PulsarClient {
2128
let logger = Logger(label: "PulsarClient")
2229
let group: EventLoopGroup

‎Sources/Pulsar/PulsarClientError.swift

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
1414

15+
// The errors thrown by the library.
1516
public enum PulsarClientError: Error, Equatable {
1617
case clientClosed
1718
case networkError

‎Sources/Pulsar/PulsarConsumer.swift

+5-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
1414

15-
/// A Pulsar Consumer, used to asynchronously consume messages from a topic.
15+
/// A Pulsar consumer used to asynchronously consume messages from a specific topic.
16+
///
17+
/// This class provides support for consuming messages from a Pulsar topic using various subscription types.
18+
/// It conforms to `AsyncSequence`, enabling iteration over received messages in an asynchronous context.
19+
/// Generic `T` represents the type of payload for the messages, conforming to `PulsarPayload`.
1620
public final class PulsarConsumer<T: PulsarPayload>: AsyncSequence, Sendable, AnyConsumer {
1721
public let consumerID: UInt64
1822
let autoAcknowledge: Bool

‎Sources/Pulsar/PulsarProducer.swift

+5-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
1414

15-
/// A Pulsar producer, used to publish messages to a topic.
15+
/// A Pulsar producer used to publish messages to a specific topic.
16+
///
17+
/// This component enables sending messages to a Pulsar topic. It supports configuration
18+
/// for schema, and other publishing parameters to ensure efficient and reliable
19+
/// message delivery.
1620
public final class PulsarProducer<T: PulsarPayload>: Sendable, AnyProducer {
1721
public let producerID: UInt64
1822
let topic: String

‎Sources/Pulsar/PulsarSchema.swift

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
1414

15+
// Supported Pulsar schemas by the library.
1516
public enum PulsarSchema: String, Equatable, Sendable {
1617
case bytes
1718
case string

0 commit comments

Comments
 (0)