envoy_sdk/host/
shared_queue.rs

1// Copyright 2020 Tetrate
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
15//! `Envoy` `Shared Queue API`.
16
17use crate::host::{self, ByteString};
18
19pub use crate::abi::proxy_wasm::types::SharedQueueHandle;
20
21/// An interface of the `Envoy` `Shared Queue API`.
22///
23/// Basic usage of [`SharedQueue`]:
24///
25/// ```
26/// # use envoy_sdk as envoy;
27/// # use envoy::host::Result;
28/// # fn action() -> Result<()> {
29/// use envoy::host::SharedQueue;
30///
31/// let shared_queue = SharedQueue::default();
32///
33/// let queue_handle = shared_queue.register("shared_queue")?;
34///
35/// shared_queue.enqueue(queue_handle, b"some value")?;
36/// # Ok(())
37/// # }
38/// ```
39///
40/// Injecting [`SharedQueue`] into a HTTP Filter as a dependency:
41///
42/// ```
43/// # use envoy_sdk as envoy;
44/// use envoy::host::SharedQueue;
45///
46/// struct MyHttpFilter<'a> {
47///     shared_queue: &'a dyn SharedQueue,
48/// }
49///
50/// impl<'a> MyHttpFilter<'a> {
51///     /// Creates a new instance parameterized with a given [`SharedQueue`] implementation.
52///     pub fn new(shared_queue: &'a dyn SharedQueue) -> Self {
53///         MyHttpFilter { shared_queue }
54///     }
55///
56///     /// Creates a new instance parameterized with the default [`SharedQueue`] implementation.
57///     pub fn default() -> Self {
58///         Self::new(SharedQueue::default())
59///     }
60/// }
61/// ```
62///
63/// [`SharedQueue`]: trait.SharedQueue.html
64pub trait SharedQueue {
65    fn register(&self, name: &str) -> host::Result<SharedQueueHandle>;
66
67    fn lookup(&self, vm_id: &str, name: &str) -> host::Result<Option<SharedQueueHandle>>;
68
69    fn dequeue(&self, queue_id: SharedQueueHandle) -> host::Result<Option<ByteString>>;
70
71    fn enqueue(&self, queue_id: SharedQueueHandle, value: &[u8]) -> host::Result<()>;
72}
73
74impl dyn SharedQueue {
75    /// Returns the default implementation that interacts with `Envoy`
76    /// through its [`ABI`].
77    ///
78    /// [`ABI`]: https://github.com/proxy-wasm/spec
79    pub fn default() -> &'static dyn SharedQueue {
80        &impls::Host
81    }
82}
83
84mod impls {
85    use super::SharedQueue;
86    use crate::abi::proxy_wasm::hostcalls;
87    use crate::abi::proxy_wasm::types::SharedQueueHandle;
88    use crate::host::{self, ByteString};
89
90    pub(super) struct Host;
91
92    impl SharedQueue for Host {
93        fn register(&self, name: &str) -> host::Result<SharedQueueHandle> {
94            hostcalls::register_shared_queue(name)
95        }
96
97        fn lookup(&self, vm_id: &str, name: &str) -> host::Result<Option<SharedQueueHandle>> {
98            hostcalls::resolve_shared_queue(vm_id, name)
99        }
100
101        fn dequeue(&self, queue_id: SharedQueueHandle) -> host::Result<Option<ByteString>> {
102            hostcalls::dequeue_shared_queue(queue_id)
103        }
104
105        fn enqueue(&self, queue_id: SharedQueueHandle, value: &[u8]) -> host::Result<()> {
106            hostcalls::enqueue_shared_queue(queue_id, value)
107        }
108    }
109}
envoy_sdk/host/shared_queue.rs

envoy_sdk/host/
shared_queue.rs
