You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Google Cloud Pub/Sub client library in [Rust](https://www.rust-lang.org/). Currently publishing, pulling and acknowledging are supported, as well as creating topics and subscriptions; other management tasks (like deleting or listing) are not yet supported.
17
+
A [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) client library for
18
+
[Rust](https://www.rust-lang.org/). It supports publishing, pulling and
19
+
acknowledging messages, as well as creating topics and subscriptions; other
20
+
management tasks (like deleting or listing) are not yet supported.
18
21
19
-
Messages can either be published/pulled as raw or, if the payload is JSON data, serialized from/deserialized into domain messages (structs or enums) via [Serde](https://serde.rs/) and [Serde JSON](https://docs.rs/serde_json). Both raw `RawPulledMessageEnvelope`s and "typed" `PulledMessage`s expose metadata like message ID, acknowledge ID, attributes, etc.
20
-
21
-
Aside from straightforward deserialization it is also possible to first transform the pulled JSON values before deserializing into domain messages which allows for generally adjusting the JSON structure as well as schema evolution.
22
+
Messages can be published and pulled as raw payloads or – when the payload is
23
+
JSON – serialized from and deserialized into domain messages (structs or enums)
24
+
via [Serde](https://serde.rs/). When pulling, the raw JSON can optionally be
25
+
transformed before deserialization, which is handy for schema evolution.
22
26
23
27
## Features
24
28
@@ -36,78 +40,95 @@ cargo add pub-sub-client
36
40
37
41
## Usage
38
42
39
-
Typically we want to use domain message:
43
+
All operations are provided by `PubSubClient`. The example below publishes a few
44
+
typed messages and then pulls and acknowledges them:
40
45
41
46
```rust
47
+
usepub_sub_client::{Error, PubSubClient};
48
+
useserde::{Deserialize, Serialize};
49
+
usestd::time::Duration;
50
+
51
+
constTOPIC_ID:&str="test";
52
+
constSUBSCRIPTION_ID:&str="test";
53
+
42
54
#[derive(Debug, Serialize, Deserialize)]
43
55
structMessage {
44
56
text:String,
45
57
}
46
-
```
47
-
48
-
To publish `Message` we need to derive `Serialize` and to pull it we need to derive `Deserialize`.
49
-
50
-
First create a `PubSubClient`, giving the path to a service account key file and the duration to refresh access tokens before they expire:
51
-
52
-
```rust
53
-
letpub_sub_client=PubSubClient::new(
54
-
"secrets/cryptic-hawk-336616-e228f9680cbc.json",
55
-
Duration::from_secs(30),
56
-
)?;
57
-
```
58
58
59
-
Things could go wrong, e.g. if the service account key file does not exist or is malformed, hence a `Result` is returned.
60
-
61
-
Then we call `publish` to publish some `messages` using the given `TOPIC_ID` and – if all is good – get back the message IDs; we do not use an ordering key nor a request timeout here and below for simplicity:
59
+
asyncfnrun() ->Result<(), Error> {
60
+
// Create a client from a service account key file, refreshing access tokens
61
+
// 30s before they expire. Fails if the key file is missing or malformed.
62
+
letpub_sub_client=PubSubClient::new(
63
+
"secrets/service-account.json",
64
+
Duration::from_secs(30),
65
+
)?;
66
+
67
+
// Publish some messages, getting back their IDs.
68
+
letmessages= ["Hello", "from pub-sub-client"]
69
+
.into_iter()
70
+
.map(|text|Message { text:text.to_string() })
71
+
.collect::<Vec<_>>();
72
+
letmessage_ids=pub_sub_client
73
+
.publish(TOPIC_ID, messages, None, None)
74
+
.await?;
75
+
println!("published messages with IDs: {}", message_ids.join(", "));
62
76
63
-
```rust
64
-
letmessages=vec!["Hello", "from pub-sub-client"]
65
-
.iter()
66
-
.map(|s|s.to_string())
67
-
.map(|text|Message { text })
68
-
.collect::<Vec<_>>();
69
-
letmessage_ids=pub_sub_client
70
-
.publish(TOPIC_ID, messages, None, None)
71
-
.await?;
72
-
letmessage_ids=message_ids.join(", ");
73
-
println!("Published messages with IDs: {message_ids}");
74
-
```
77
+
// Pull at most 42 messages, deserializing each into a `Message`.
78
+
letpulled_messages=pub_sub_client
79
+
.pull::<Message>(SUBSCRIPTION_ID, 42, None)
80
+
.await?;
75
81
76
-
Next we call `pull` to get at most the given `42` messages from the given `SUBSCRIPTION_ID`:
82
+
forpulled_messageinpulled_messages {
83
+
matchpulled_message.message {
84
+
Ok(m) =>println!("pulled message with text \"{}\"", m.text),
println!("Acknowledged message with ID {}", pulled_message.id);
99
-
}
100
-
```
110
+
Messages can also be published and pulled raw via `publish_raw` and `pull_raw`,
111
+
giving direct access to the Base64 encoded payload and all metadata. When
112
+
pulling, `pull_with_transform` lets you adjust the raw JSON value before it is
113
+
deserialized into a domain message, which is useful for schema evolution. See
114
+
[`examples/transform.rs`](examples/transform.rs).
101
115
102
-
For successfully deserialized messages we call `acknowledge` with the acknowledge ID taken from the envelope.
116
+
### Examples and local testing
103
117
104
-
### Raw messages and transformations
118
+
The [`examples`](examples) directory contains complete programs:
119
+
[`simple`](examples/simple.rs) for typed publishing and pulling and
120
+
[`transform`](examples/transform.rs) for transformations. They read the service
121
+
account key path from the `SERVICE_ACCOUNT_PATH` environment variable:
105
122
106
-
The walkthrough above uses typed domain messages, but messages can also be published and pulled raw via `publish_raw` and `pull_raw`, giving direct access to the Base64 encoded payload and all metadata. When pulling, `pull_with_transform` lets you adjust the raw JSON value before it is deserialized into a domain message, which is handy for schema evolution.
123
+
```shell
124
+
SERVICE_ACCOUNT_PATH=secrets/service-account.json cargo run --example simple
125
+
```
107
126
108
-
See the [`examples`](examples) directory for complete programs: [`simple`](examples/simple.rs) for typed publishing and pulling and [`transform`](examples/transform.rs) for transformations.
127
+
By default the client talks to `https://pubsub.googleapis.com`. Set the
128
+
`PUB_SUB_BASE_URL` environment variable to point it at a different endpoint,
129
+
such as a local [Pub/Sub emulator](https://cloud.google.com/pubsub/docs/emulator).
109
130
110
-
## Contribution policy ##
131
+
## Contribution policy
111
132
112
133
Contributions via GitHub pull requests are gladly accepted from their original author. Along with
113
134
any pull requests, please state that the contribution is your original work and that you license the
@@ -116,8 +137,7 @@ explicitly, by submitting any copyrighted material via pull request, email, or o
116
137
to license the material under the project's open source license and warrant that you have the legal
117
138
authority to do so.
118
139
119
-
## License ##
140
+
## License
120
141
121
142
This code is open source software licensed under the
0 commit comments