fdomain_client/
fidl.rs

1// Copyright 2024 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::{
6    AnyHandle, AsHandleRef, Channel, ChannelMessageStream, ChannelWriter, Error, Handle,
7    HandleBased, HandleInfo, MessageBuf,
8};
9use fidl::epitaph::ChannelEpitaphExt;
10use fidl_fuchsia_fdomain as proto;
11use fuchsia_sync::Mutex;
12use futures::{Stream, StreamExt, TryStream};
13use std::cell::RefCell;
14use std::marker::PhantomData;
15use std::sync::Arc;
16use std::task::Poll;
17
18pub trait FDomainFlexibleIntoResult<T> {
19    fn into_result_fdomain<P: ProtocolMarker>(
20        self,
21        method_name: &'static str,
22    ) -> Result<T, fidl::Error>;
23}
24
25impl<T> FDomainFlexibleIntoResult<T> for fidl::encoding::Flexible<T> {
26    fn into_result_fdomain<P: ProtocolMarker>(
27        self,
28        method_name: &'static str,
29    ) -> Result<T, fidl::Error> {
30        match self {
31            fidl::encoding::Flexible::Ok(ok) => Ok(ok),
32            fidl::encoding::Flexible::FrameworkErr(fidl::encoding::FrameworkErr::UnknownMethod) => {
33                Err(fidl::Error::UnsupportedMethod { method_name, protocol_name: P::DEBUG_NAME })
34            }
35        }
36    }
37}
38
39impl<T, E> FDomainFlexibleIntoResult<Result<T, E>> for fidl::encoding::FlexibleResult<T, E> {
40    fn into_result_fdomain<P: ProtocolMarker>(
41        self,
42        method_name: &'static str,
43    ) -> Result<Result<T, E>, fidl::Error> {
44        match self {
45            fidl::encoding::FlexibleResult::Ok(ok) => Ok(Ok(ok)),
46            fidl::encoding::FlexibleResult::DomainErr(err) => Ok(Err(err)),
47            fidl::encoding::FlexibleResult::FrameworkErr(
48                fidl::encoding::FrameworkErr::UnknownMethod,
49            ) => Err(fidl::Error::UnsupportedMethod { method_name, protocol_name: P::DEBUG_NAME }),
50        }
51    }
52}
53
54#[derive(Debug)]
55pub struct FDomainProxyChannel(Mutex<ChannelMessageStream>, ChannelWriter);
56
57impl FDomainProxyChannel {
58    pub fn on_closed(&self) -> crate::OnFDomainSignals {
59        self.1.as_channel().on_closed()
60    }
61
62    pub fn read_etc(
63        &self,
64        ctx: &mut std::task::Context<'_>,
65        bytes: &mut Vec<u8>,
66        handles: &mut Vec<HandleInfo>,
67    ) -> Poll<Result<(), Option<crate::Error>>> {
68        let Some(got) = std::task::ready!(self.0.lock().poll_next_unpin(ctx)) else {
69            return Poll::Ready(Err(Some(Error::StreamingAborted)));
70        };
71
72        match got {
73            Ok(got) => {
74                *bytes = got.bytes;
75                *handles = got.handles;
76                Poll::Ready(Ok(()))
77            }
78            Err(Error::FDomain(proto::Error::TargetError(i)))
79                if i == fidl::Status::PEER_CLOSED.into_raw() =>
80            {
81                Poll::Ready(Err(None))
82            }
83            Err(e) => Poll::Ready(Err(Some(e))),
84        }
85    }
86}
87
88impl ::fidl::encoding::ProxyChannelBox<FDomainResourceDialect> for FDomainProxyChannel {
89    fn recv_etc_from(
90        &self,
91        ctx: &mut std::task::Context<'_>,
92        buf: &mut MessageBuf,
93    ) -> Poll<Result<(), Option<Error>>> {
94        let Some(got) = std::task::ready!(self.0.lock().poll_next_unpin(ctx)) else {
95            return Poll::Ready(Err(Some(Error::StreamingAborted)));
96        };
97
98        match got {
99            Ok(got) => {
100                *buf = got;
101                Poll::Ready(Ok(()))
102            }
103            Err(Error::FDomain(proto::Error::TargetError(i)))
104                if i == fidl::Status::PEER_CLOSED.into_raw() =>
105            {
106                Poll::Ready(Err(None))
107            }
108            Err(e) => Poll::Ready(Err(Some(e))),
109        }
110    }
111
112    fn write_etc(&self, bytes: &[u8], handles: &mut [HandleInfo]) -> Result<(), Option<Error>> {
113        let mut handle_ops = Vec::new();
114        for handle in handles {
115            handle_ops.push(crate::channel::HandleOp::Move(
116                std::mem::replace(&mut handle.handle, AnyHandle::invalid()).into(),
117                handle.rights,
118            ));
119        }
120        let _ = self.1.fdomain_write_etc(bytes, handle_ops);
121        Ok(())
122    }
123
124    fn is_closed(&self) -> bool {
125        self.0.lock().is_closed()
126    }
127
128    fn unbox(self) -> Channel {
129        self.0.into_inner().rejoin(self.1)
130    }
131
132    fn as_channel(&self) -> &Channel {
133        self.1.as_channel()
134    }
135}
136
137#[derive(Debug, Copy, Clone, Default)]
138pub struct FDomainResourceDialect;
139impl ::fidl::encoding::ResourceDialect for FDomainResourceDialect {
140    type Handle = Handle;
141    type MessageBufEtc = MessageBuf;
142    type ProxyChannel = Channel;
143
144    #[inline]
145    fn with_tls_buf<R>(f: impl FnOnce(&mut ::fidl::encoding::TlsBuf<Self>) -> R) -> R {
146        thread_local!(static TLS_BUF: RefCell<::fidl::encoding::TlsBuf<FDomainResourceDialect>> =
147            RefCell::new(::fidl::encoding::TlsBuf::default()));
148        TLS_BUF.with(|buf| f(&mut buf.borrow_mut()))
149    }
150}
151
152impl ::fidl::encoding::MessageBufFor<FDomainResourceDialect> for MessageBuf {
153    fn new() -> MessageBuf {
154        MessageBuf { bytes: Vec::new(), handles: Vec::new() }
155    }
156
157    fn split_mut(&mut self) -> (&mut Vec<u8>, &mut Vec<HandleInfo>) {
158        (&mut self.bytes, &mut self.handles)
159    }
160}
161
162impl Into<::fidl::TransportError> for Error {
163    fn into(self) -> ::fidl::TransportError {
164        match self {
165            Error::FDomain(proto::Error::TargetError(i)) => {
166                ::fidl::TransportError::Status(fidl::Status::from_raw(i))
167            }
168            Error::SocketWrite(proto::WriteSocketError {
169                error: proto::Error::TargetError(i),
170                ..
171            }) => ::fidl::TransportError::Status(fidl::Status::from_raw(i)),
172            Error::ChannelWrite(proto::WriteChannelError::Error(proto::Error::TargetError(i))) => {
173                ::fidl::TransportError::Status(fidl::Status::from_raw(i))
174            }
175            Error::ChannelWrite(proto::WriteChannelError::OpErrors(ops)) => {
176                let Some(op) = ops.into_iter().find_map(|x| x) else {
177                    let err = Box::<dyn std::error::Error + Send + Sync>::from(
178                        "Channel write handle operation reported failure with no status!"
179                            .to_owned(),
180                    );
181                    return ::fidl::TransportError::Other(err.into());
182                };
183                let op = *op;
184                Error::FDomain(op).into()
185            }
186            other => ::fidl::TransportError::Other(std::sync::Arc::new(other)),
187        }
188    }
189}
190
191impl ::fidl::encoding::ProxyChannelFor<FDomainResourceDialect> for Channel {
192    type Boxed = FDomainProxyChannel;
193    type Error = Error;
194    type HandleDisposition = HandleInfo;
195
196    fn boxed(self) -> Self::Boxed {
197        let (a, b) = self.stream().unwrap();
198        FDomainProxyChannel(Mutex::new(a), b)
199    }
200
201    fn write_etc(&self, bytes: &[u8], handles: &mut [HandleInfo]) -> Result<(), Option<Error>> {
202        let mut handle_ops = Vec::new();
203        for handle in handles {
204            handle_ops.push(crate::channel::HandleOp::Move(
205                std::mem::replace(&mut handle.handle, AnyHandle::invalid()).into(),
206                handle.rights,
207            ));
208        }
209        let _ = self.fdomain_write_etc(bytes, handle_ops);
210        Ok(())
211    }
212}
213
214impl ::fidl::epitaph::ChannelLike for Channel {
215    fn write_epitaph(&self, bytes: &[u8]) -> Result<(), ::fidl::TransportError> {
216        let _ = self.write(bytes, vec![]);
217        Ok(())
218    }
219}
220
221impl ::fidl::encoding::HandleFor<FDomainResourceDialect> for Handle {
222    // This has to be static, so we can't encode a duplicate operation here
223    // anyway. So use HandleInfo.
224    type HandleInfo = HandleInfo;
225
226    fn invalid() -> Self {
227        Handle::invalid()
228    }
229
230    fn is_invalid(&self) -> bool {
231        self.client.upgrade().is_none()
232    }
233}
234
235impl ::fidl::encoding::HandleDispositionFor<FDomainResourceDialect> for HandleInfo {
236    fn from_handle(handle: Handle, object_type: fidl::ObjectType, rights: fidl::Rights) -> Self {
237        HandleInfo { handle: AnyHandle::from_handle(handle, object_type), rights }
238    }
239}
240
241impl ::fidl::encoding::HandleInfoFor<FDomainResourceDialect> for HandleInfo {
242    fn consume(
243        &mut self,
244        expected_object_type: fidl::ObjectType,
245        expected_rights: fidl::Rights,
246    ) -> Result<Handle, ::fidl::Error> {
247        let handle_info = std::mem::replace(
248            self,
249            HandleInfo {
250                handle: crate::AnyHandle::Unknown(Handle::invalid(), fidl::ObjectType::NONE),
251                rights: fidl::Rights::empty(),
252            },
253        );
254        let received_object_type = handle_info.handle.object_type();
255        if expected_object_type != fidl::ObjectType::NONE
256            && received_object_type != fidl::ObjectType::NONE
257            && expected_object_type != received_object_type
258        {
259            return Err(fidl::Error::IncorrectHandleSubtype {
260                // TODO: Find a way to put something better in here, either by
261                // expanding what FIDL can return or casting the protocol values
262                // to something FIDL can read.
263                expected: fidl::ObjectType::NONE,
264                received: fidl::ObjectType::NONE,
265            });
266        }
267
268        let received_rights = handle_info.rights;
269        if expected_rights != fidl::Rights::SAME_RIGHTS
270            && received_rights != fidl::Rights::SAME_RIGHTS
271            && expected_rights != received_rights
272        {
273            if !received_rights.contains(expected_rights) {
274                return Err(fidl::Error::MissingExpectedHandleRights {
275                    // TODO: As above, report something better here.
276                    missing_rights: fidl::Rights::empty(),
277                });
278            }
279
280            // TODO: The normal FIDL bindings call zx_handle_replace here to
281            // forcibly downgrade the handle rights. That's a whole IO operation
282            // for us so we won't bother, but maybe we should do something else?
283        }
284        Ok(handle_info.handle.into())
285    }
286
287    fn drop_in_place(&mut self) {
288        *self = HandleInfo {
289            handle: crate::AnyHandle::Unknown(Handle::invalid(), fidl::ObjectType::NONE),
290            rights: fidl::Rights::empty(),
291        };
292    }
293}
294
295impl ::fidl::encoding::EncodableAsHandle for crate::Event {
296    type Dialect = FDomainResourceDialect;
297}
298
299impl ::fidl::encoding::EncodableAsHandle for crate::EventPair {
300    type Dialect = FDomainResourceDialect;
301}
302
303impl ::fidl::encoding::EncodableAsHandle for crate::Socket {
304    type Dialect = FDomainResourceDialect;
305}
306
307impl ::fidl::encoding::EncodableAsHandle for crate::Channel {
308    type Dialect = FDomainResourceDialect;
309}
310
311impl ::fidl::encoding::EncodableAsHandle for crate::Handle {
312    type Dialect = FDomainResourceDialect;
313}
314
315impl<T: ProtocolMarker> ::fidl::encoding::EncodableAsHandle for ClientEnd<T> {
316    type Dialect = FDomainResourceDialect;
317}
318
319impl<T: ProtocolMarker> ::fidl::encoding::EncodableAsHandle for ServerEnd<T> {
320    type Dialect = FDomainResourceDialect;
321}
322
323/// Implementations of this trait can be used to manufacture instances of a FIDL
324/// protocol and get metadata about a particular protocol.
325pub trait ProtocolMarker: Sized + Send + Sync + 'static {
326    /// The type of the structure against which FIDL requests are made.
327    /// Queries made against the proxy are sent to the paired `ServerEnd`.
328    type Proxy: Proxy<Protocol = Self>;
329
330    /// The type of the stream of requests coming into a server.
331    type RequestStream: RequestStream<Protocol = Self>;
332
333    /// The name of the protocol suitable for debug purposes.
334    ///
335    /// For discoverable protocols, this should be identical to
336    /// `<Self as DiscoverableProtocolMarker>::PROTOCOL_NAME`.
337    const DEBUG_NAME: &'static str;
338}
339
340/// A marker for a particular FIDL protocol that is also discoverable.
341///
342/// Discoverable protocols may be referred to by a string name, and can be
343/// conveniently exported in a service directory via an entry of that name.
344///
345/// If you get an error about this trait not being implemented, you probably
346/// need to add the `@discoverable` attribute to the FIDL protocol, like this:
347///
348/// ```fidl
349/// @discoverable
350/// protocol MyProtocol { ... };
351/// ```
352pub trait DiscoverableProtocolMarker: ProtocolMarker {
353    /// The name of the protocol (to be used for service lookup and discovery).
354    const PROTOCOL_NAME: &'static str = <Self as ProtocolMarker>::DEBUG_NAME;
355}
356
357/// A type which allows querying a remote FIDL server over a channel.
358pub trait Proxy: Sized + Send + Sync {
359    /// The protocol which this `Proxy` controls.
360    type Protocol: ProtocolMarker<Proxy = Self>;
361
362    /// Create a proxy over the given channel.
363    fn from_channel(inner: Channel) -> Self;
364
365    /// Attempt to convert the proxy back into a channel.
366    ///
367    /// This will only succeed if there are no active clones of this proxy
368    /// and no currently-alive `EventStream` or response futures that came from
369    /// this proxy.
370    fn into_channel(self) -> Result<Channel, Self>;
371
372    /// Get a reference to the proxy's underlying channel.
373    ///
374    /// This should only be used for non-effectful operations. Reading or
375    /// writing to the channel is unsafe because the proxy assumes it has
376    /// exclusive control over these operations.
377    fn as_channel(&self) -> &Channel;
378
379    /// Get the client supporting this proxy. We call this a "domain" here because:
380    /// * Client is especially overloaded in contexts where this is useful.
381    /// * We simulate this call for target-side FIDL proxies, so it isn't always
382    ///   really a client.
383    fn domain(&self) -> Arc<crate::Client> {
384        self.as_channel().domain()
385    }
386}
387
388/// A stream of requests coming into a FIDL server over a channel.
389pub trait RequestStream: Sized + Send + Stream + TryStream<Error = fidl::Error> + Unpin {
390    /// The protocol which this `RequestStream` serves.
391    type Protocol: ProtocolMarker<RequestStream = Self>;
392
393    /// The control handle for this `RequestStream`.
394    type ControlHandle: ControlHandle;
395
396    /// Returns a copy of the `ControlHandle` for the given stream.
397    /// This handle can be used to send events or shut down the request stream.
398    fn control_handle(&self) -> Self::ControlHandle;
399
400    /// Create a request stream from the given channel.
401    fn from_channel(inner: Channel) -> Self;
402
403    /// Convert to a `ServeInner`
404    fn into_inner(self) -> (std::sync::Arc<fidl::ServeInner<FDomainResourceDialect>>, bool);
405
406    /// Convert from a `ServeInner`
407    fn from_inner(
408        inner: std::sync::Arc<fidl::ServeInner<FDomainResourceDialect>>,
409        is_terminated: bool,
410    ) -> Self;
411}
412
413/// A type associated with a `RequestStream` that can be used to send FIDL
414/// events or to shut down the request stream.
415pub trait ControlHandle {
416    /// Set the server to shutdown. The underlying channel is only closed the
417    /// next time the stream is polled.
418    fn shutdown(&self);
419
420    /// Returns true if the server has received the `PEER_CLOSED` signal.
421    fn is_closed(&self) -> bool;
422
423    /// Returns a future that completes when the server receives the
424    /// `PEER_CLOSED` signal.
425    fn on_closed(&self) -> crate::OnFDomainSignals;
426}
427
428/// A type associated with a particular two-way FIDL method, used by servers to
429/// send a response to the client.
430pub trait Responder {
431    /// The control handle for this protocol.
432    type ControlHandle: ControlHandle;
433
434    /// Returns the `ControlHandle` for this protocol.
435    fn control_handle(&self) -> &Self::ControlHandle;
436
437    /// Drops the responder without setting the channel to shutdown.
438    ///
439    /// This method shouldn't normally be used. Instead, send a response to
440    /// prevent the channel from shutting down.
441    fn drop_without_shutdown(self);
442}
443
444/// The Request type associated with a Marker.
445pub type Request<Marker> = <<Marker as ProtocolMarker>::RequestStream as futures::TryStream>::Ok;
446
447/// The `Client` end of a FIDL connection.
448#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
449pub struct ClientEnd<T: ProtocolMarker> {
450    inner: Channel,
451    phantom: PhantomData<T>,
452}
453
454impl<T: ProtocolMarker> ClientEnd<T> {
455    /// Create a new client from the provided channel.
456    pub fn new(inner: Channel) -> Self {
457        ClientEnd { inner, phantom: PhantomData }
458    }
459
460    /// Get a reference to the underlying channel
461    pub fn channel(&self) -> &Channel {
462        &self.inner
463    }
464
465    /// Extract the underlying channel.
466    pub fn into_channel(self) -> Channel {
467        self.inner
468    }
469}
470
471impl<'c, T: ProtocolMarker> ClientEnd<T> {
472    /// Convert the `ClientEnd` into a `Proxy` through which FIDL calls may be made.
473    pub fn into_proxy(self) -> T::Proxy {
474        T::Proxy::from_channel(self.inner)
475    }
476}
477
478impl<T: ProtocolMarker> From<ClientEnd<T>> for Handle {
479    fn from(client: ClientEnd<T>) -> Handle {
480        client.into_channel().into()
481    }
482}
483
484impl<T: ProtocolMarker> From<Handle> for ClientEnd<T> {
485    fn from(handle: Handle) -> Self {
486        ClientEnd { inner: handle.into(), phantom: PhantomData }
487    }
488}
489
490impl<T: ProtocolMarker> From<Channel> for ClientEnd<T> {
491    fn from(chan: Channel) -> Self {
492        ClientEnd { inner: chan, phantom: PhantomData }
493    }
494}
495
496impl<T: ProtocolMarker> AsHandleRef for ClientEnd<T> {
497    fn as_handle_ref(&self) -> crate::HandleRef<'_> {
498        AsHandleRef::as_handle_ref(&self.inner)
499    }
500
501    fn object_type() -> fidl::ObjectType {
502        <Channel as AsHandleRef>::object_type()
503    }
504}
505
506impl<T: ProtocolMarker> HandleBased for ClientEnd<T> {
507    fn close(self) -> impl Future<Output = Result<(), Error>> {
508        let h = <Self as Into<Handle>>::into(self);
509        Handle::close(h)
510    }
511
512    fn duplicate_handle(&self, rights: fidl::Rights) -> impl Future<Output = Result<Self, Error>> {
513        let fut = self.as_handle_ref().duplicate(rights);
514        async move { fut.await.map(|handle| Self::from(handle)) }
515    }
516
517    fn replace_handle(self, rights: fidl::Rights) -> impl Future<Output = Result<Self, Error>> {
518        let h = <Self as Into<Handle>>::into(self);
519        async move { h.replace(rights).await.map(|handle| Self::from(handle)) }
520    }
521
522    fn into_handle(self) -> Handle {
523        self.into()
524    }
525
526    fn from_handle(handle: Handle) -> Self {
527        Self::from(handle)
528    }
529
530    fn into_handle_based<H: HandleBased>(self) -> H {
531        H::from_handle(self.into_handle())
532    }
533
534    fn from_handle_based<H: HandleBased>(h: H) -> Self {
535        Self::from_handle(h.into_handle())
536    }
537
538    fn invalidate(&mut self) {
539        self.inner.invalidate();
540    }
541}
542
543/// The `Server` end of a FIDL connection.
544#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
545pub struct ServerEnd<T: ProtocolMarker> {
546    inner: Channel,
547    phantom: PhantomData<T>,
548}
549
550impl<T: ProtocolMarker> ServerEnd<T> {
551    /// Create a new `ServerEnd` from the provided channel.
552    pub fn new(inner: Channel) -> ServerEnd<T> {
553        ServerEnd { inner, phantom: PhantomData }
554    }
555
556    /// Get a reference to the underlying channel
557    pub fn channel(&self) -> &Channel {
558        &self.inner
559    }
560
561    /// Extract the inner channel.
562    pub fn into_channel(self) -> Channel {
563        self.inner
564    }
565
566    /// Create a stream of requests off of the channel.
567    pub fn into_stream(self) -> T::RequestStream
568    where
569        T: ProtocolMarker,
570    {
571        T::RequestStream::from_channel(self.inner)
572    }
573
574    /// Create a stream of requests and an event-sending handle
575    /// from the channel.
576    pub fn into_stream_and_control_handle(
577        self,
578    ) -> (T::RequestStream, <T::RequestStream as RequestStream>::ControlHandle)
579    where
580        T: ProtocolMarker,
581    {
582        let stream = self.into_stream();
583        let control_handle = stream.control_handle();
584        (stream, control_handle)
585    }
586
587    /// Writes an epitaph into the underlying channel before closing it.
588    pub fn close_with_epitaph(self, status: fidl::Status) -> Result<(), fidl::Error> {
589        self.inner.close_with_epitaph(status)
590    }
591}
592
593impl<T: ProtocolMarker> From<ServerEnd<T>> for Handle {
594    fn from(server: ServerEnd<T>) -> Handle {
595        server.into_channel().into()
596    }
597}
598
599impl<T: ProtocolMarker> From<Handle> for ServerEnd<T> {
600    fn from(handle: Handle) -> Self {
601        ServerEnd { inner: handle.into(), phantom: PhantomData }
602    }
603}
604
605impl<T: ProtocolMarker> From<Channel> for ServerEnd<T> {
606    fn from(chan: Channel) -> Self {
607        ServerEnd { inner: chan, phantom: PhantomData }
608    }
609}
610
611impl<T: ProtocolMarker> AsHandleRef for ServerEnd<T> {
612    fn as_handle_ref(&self) -> crate::HandleRef<'_> {
613        AsHandleRef::as_handle_ref(&self.inner)
614    }
615
616    fn object_type() -> fidl::ObjectType {
617        <Channel as AsHandleRef>::object_type()
618    }
619}
620
621impl<T: ProtocolMarker> HandleBased for ServerEnd<T> {
622    fn close(self) -> impl Future<Output = Result<(), Error>> {
623        let h = <Self as Into<Handle>>::into(self);
624        Handle::close(h)
625    }
626
627    fn duplicate_handle(&self, rights: fidl::Rights) -> impl Future<Output = Result<Self, Error>> {
628        let fut = self.as_handle_ref().duplicate(rights);
629        async move { fut.await.map(|handle| Self::from(handle)) }
630    }
631
632    fn replace_handle(self, rights: fidl::Rights) -> impl Future<Output = Result<Self, Error>> {
633        let h = <Self as Into<Handle>>::into(self);
634        async move { h.replace(rights).await.map(|handle| Self::from(handle)) }
635    }
636
637    fn into_handle(self) -> Handle {
638        self.into()
639    }
640
641    fn from_handle(handle: Handle) -> Self {
642        Self::from(handle)
643    }
644
645    fn into_handle_based<H: HandleBased>(self) -> H {
646        H::from_handle(self.into_handle())
647    }
648
649    fn from_handle_based<H: HandleBased>(h: H) -> Self {
650        Self::from_handle(h.into_handle())
651    }
652
653    fn invalidate(&mut self) {
654        self.inner.invalidate();
655    }
656}
fdomain_client/fidl.rs

fdomain_client/
fidl.rs
