mirror of https://github.com/dapr/rust-sdk.git
docs: add daprdocs for the rust sdk (#126)
* init docs Signed-off-by: mikeee <hey@mike.ee> * docs: add client methods (service invocation/state management/pubsub) Signed-off-by: mikeee <hey@mike.ee> * rustify contributing docs Signed-off-by: mikeee <hey@mike.ee> * add: wip/alpha notice Signed-off-by: Mike Nguyen <hey@mike.ee> * update: alpha notice Signed-off-by: Mike Nguyen <hey@mike.ee> * docs: add client instantiation Signed-off-by: mikeee <hey@mike.ee> --------- Signed-off-by: mikeee <hey@mike.ee> Signed-off-by: Mike Nguyen <hey@mike.ee>
This commit is contained in:
Mike Nguyen
GitHub
parent
396f571d96
commit
c6048ef1a2
|
|
@ -0,0 +1,25 @@
|
|||
# Dapr Rust SDK documentation
|
||||
|
||||
This page covers how the documentation is structured for the Dapr Rust SDK
|
||||
|
||||
## Dapr Docs
|
||||
|
||||
All Dapr documentation is hosted at [docs.dapr.io](https://docs.dapr.io), including the docs for the [Rust SDK](https://docs.dapr.io/developing-applications/sdks/rust/). Head over there if you want to read the docs.
|
||||
|
||||
### Rust SDK docs source
|
||||
|
||||
Although the docs site code and content is in the [docs repo](https://github.com/dapr/docs), the Go SDK content and images are within the `content` and `static` directories, respectively.
|
||||
|
||||
This allows separation of roles and expertise between maintainers, and makes it easy to find the docs files you are looking for.
|
||||
|
||||
## Writing Rust SDK docs
|
||||
|
||||
To get up and running to write Go SDK docs, visit the [docs repo](https://github.com/dapr/docs) to initialize your environment. It will clone both the docs repo and this repo, so you can make changes and see it rendered within the site instantly, as well as commit and PR into this repo.
|
||||
|
||||
Make sure to read the [docs contributing guide](https://docs.dapr.io/contributing/contributing-docs/) for information on style/semantics/etc.
|
||||
|
||||
## Docs architecture
|
||||
|
||||
The docs site is built on [Hugo](https://gohugo.io), which lives in the docs repo. This repo is setup as a git submodule so that when the repo is cloned and initialized, the rust repo, along with the docs, are cloned as well.
|
||||
|
||||
Then, in the Hugo configuration file, the `daprdocs/content` and `daprdocs/static` directories are redirected to the `daprdocs/developing-applications/sdks/rust` and `static/go` directories, respectively. Thus, all the content within this repo is folded into the main docs site.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Contributing to the Rust SDK"
|
||||
linkTitle: "Rust SDK"
|
||||
weight: 3000
|
||||
description: Guidelines for contributing to the Dapr Rust SDK
|
||||
---
|
||||
|
||||
When contributing to the [Rust SDK](https://github.com/dapr/rust-sdk) the following rules and best-practices should be followed.
|
||||
|
||||
## Examples
|
||||
|
||||
The `examples` directory contains code samples for users to run to try out specific functionality of the various Rust SDK packages and extensions. It also hosts component examples used for validation. When writing new and updated samples keep in mind:
|
||||
|
||||
- All examples should be runnable on Windows, Linux, and MacOS. While Rust code is consistent among operating systems aside from minor OS-feature gating, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}})
|
||||
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
|
||||
- Examples should be pass validation and include mechanical markdown steps and be added to the validation workflow [TBA](#)
|
||||
|
||||
## Docs
|
||||
|
||||
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:
|
||||
|
||||
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these.
|
||||
- All files and directories should be prefixed with `rust-` to ensure all file/directory names are globally unique across all Dapr documentation.
|
||||
|
||||
## Update Protobufs
|
||||
|
||||
To pull the protobufs from the `dapr/dapr` repo you can run the script in the repo root like so:
|
||||
|
||||
```bash
|
||||
./update-protos.sh
|
||||
```
|
||||
|
||||
By default, the script fetches the latest proto updates from the master branch of the Dapr repository. If you need to choose a specific release or version, use the -v flag:
|
||||
|
||||
```bash
|
||||
./update-protos.sh -v v1.13.0
|
||||
```
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Dapr Rust SDK"
|
||||
linkTitle: "Rust"
|
||||
weight: 1000
|
||||
description: Rust SDK packages for developing Dapr applications
|
||||
no_list: true
|
||||
cascade:
|
||||
github_repo: https://github.com/dapr/rust-sdk
|
||||
github_subdir: daprdocs/content/en/rust-sdk-docs
|
||||
path_base_for_github_subdir: content/en/developing-applications/sdks/rust/
|
||||
github_branch: main
|
||||
---
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
The Dapr Rust-SDK is currently in Alpha. Work is underway to bring it to a stable release and will likely involve breaking changes.
|
||||
{{% /alert %}}
|
||||
|
||||
A client library to help build Dapr applications using Rust. This client is targeting support for all public Dapr APIs while focusing on idiomatic Rust experiences and developer productivity.
|
||||
|
||||
{{< cardpane >}}
|
||||
{{< card title="**Client**">}}
|
||||
Use the Rust Client SDK for invoking public Dapr APIs
|
||||
|
||||
[**Learn more about the Rust Client SDK**]({{< ref rust-client >}})
|
||||
{{< /card >}}
|
||||
{{< /cardpane >}}
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Getting started with the Dapr client Rust SDK"
|
||||
linkTitle: "Client"
|
||||
weight: 20000
|
||||
description: How to get up and running with the Dapr Rust SDK
|
||||
no_list: true
|
||||
---
|
||||
|
||||
The Dapr client package allows you to interact with other Dapr applications from a Rust application.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
The Dapr Rust-SDK is currently in Alpha. Work is underway to bring it to a stable release and will likely involve breaking changes.
|
||||
{{% /alert %}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
|
||||
- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
|
||||
- [Rust installed](https://www.rust-lang.org/tools/install)
|
||||
|
||||
|
||||
## Import the client package
|
||||
|
||||
Add Dapr to your `cargo.toml`
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
# Other dependencies
|
||||
dapr = "0.13.0"
|
||||
```
|
||||
|
||||
You can either reference `dapr::Client` or bind the full path to a new name as follows:
|
||||
```rust
|
||||
use dapr::Client as DaprClient
|
||||
```
|
||||
|
||||
## Instantiating the Dapr client
|
||||
|
||||
```rust
|
||||
const addr: String = "https://127.0.0.1";
|
||||
const port: String = "50001";
|
||||
|
||||
let mut client = dapr::Client::<dapr::client::TonicClient>::connect(addr,
|
||||
port).await?;
|
||||
```
|
||||
|
||||
|
||||
## Building blocks
|
||||
|
||||
The Rust SDK allows you to interface with the [Dapr building blocks]({{< ref building-blocks >}}).
|
||||
|
||||
### Service Invocation
|
||||
|
||||
To invoke a specific method on another service running with Dapr sidecar, the Dapr client Go SDK provides two options:
|
||||
|
||||
Invoke a service
|
||||
```rust
|
||||
let response = client
|
||||
.invoke_service("service-to-invoke", "method-to-invoke", Some(data))
|
||||
.await
|
||||
.unwrap();
|
||||
```
|
||||
|
||||
|
||||
For a full guide on service invocation, visit [How-To: Invoke a service]({{< ref howto-invoke-discover-services.md >}}).
|
||||
|
||||
### State Management
|
||||
|
||||
The Dapr Client provides access to these state management methods: `save_state`, `get_state`, `delete_state` that can be used like so:
|
||||
|
||||
```rust
|
||||
let store_name = "store-name";
|
||||
let state_key = "state-key";
|
||||
|
||||
let states = vec![(state_key, ("state-value").as_bytes().to_vec())];
|
||||
|
||||
// save state with the key "state-key" and value "state-value"
|
||||
client.save_state(store_name, states).await?;
|
||||
|
||||
// get state for key "state-key"
|
||||
let response = client.get_state(store_name, state_key, None).await.unwrap();
|
||||
|
||||
// delete state for key "state-key"
|
||||
client.delete_state(store_name, state_key, None).await?;
|
||||
```
|
||||
|
||||
> **Note:** The `save_state` method currently performs a 'bulk' save but this will be refactored
|
||||
|
||||
|
||||
For a full guide on state management, visit [How-To: Save & get state]({{< ref howto-get-save-state.md >}}).
|
||||
|
||||
### Publish Messages
|
||||
To publish data onto a topic, the Dapr Go client provides a simple method:
|
||||
|
||||
```rust
|
||||
let pubsub_name = "pubsub-name".to_string();
|
||||
let pubsub_topic = "topic-name".to_string();
|
||||
let pubsub_content_type = "text/plain".to_string();
|
||||
|
||||
let data = "content".to_string().into_bytes();
|
||||
client
|
||||
.publish_event(pubsub_name, pubsub_topic, pubsub_content_type, data, None)
|
||||
.await?;
|
||||
```
|
||||
|
||||
For a full guide on pub/sub, visit [How-To: Publish & subscribe]({{< ref howto-publish-subscribe.md >}}).
|
||||
|
||||
## Related links
|
||||
[Rust SDK Examples](https://github.com/dapr/rust-sdk/tree/master/examples)
|
||||
Loading…
Reference in New Issue