elf_runner/
component.rs

1// Copyright 2021 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::config::ElfProgramConfig;
6use crate::runtime_dir::RuntimeDirectory;
7use crate::Job;
8use async_trait::async_trait;
9use fidl::endpoints::{ClientEnd, Proxy};
10use fidl_fuchsia_component_runner::ComponentControllerOnEscrowRequest;
11use fidl_fuchsia_process_lifecycle::{LifecycleEvent, LifecycleProxy};
12use futures::future::{join_all, BoxFuture, FutureExt};
13use futures::stream::BoxStream;
14use futures::StreamExt;
15use log::{error, warn};
16use moniker::Moniker;
17use runner::component::Controllable;
18use std::ops::DerefMut;
19use std::sync::{Arc, Mutex};
20use zx::{self as zx, AsHandleRef, HandleBased, Process, Task};
21use {fidl_fuchsia_io as fio, fuchsia_async as fasync};
22
23/// Immutable information about the component.
24///
25/// These information is shared with [`crate::ComponentSet`].
26pub struct ElfComponentInfo {
27    /// Moniker of the ELF component.
28    moniker: Moniker,
29
30    /// Instance token of the component.
31    component_instance: zx::Event,
32
33    /// Job in which the underlying process that represents the component is
34    /// running.
35    job: Arc<Job>,
36
37    /// We need to remember if we marked the main process as critical, because if we're asked to
38    /// kill a component that has such a marking it'll bring down everything.
39    main_process_critical: bool,
40
41    /// URL with which the component was launched.
42    component_url: String,
43
44    /// A connection to the component's outgoing directory.
45    ///
46    /// This option will be present if the ELF runner needs to open capabilities
47    /// exposed by the ELF component.
48    outgoing_directory_for_memory_attribution: Option<ClientEnd<fio::DirectoryMarker>>,
49
50    /// Configurations from the program block.
51    program_config: ElfProgramConfig,
52}
53
54impl ElfComponentInfo {
55    pub fn get_url(&self) -> &String {
56        &self.component_url
57    }
58
59    pub fn get_moniker(&self) -> &Moniker {
60        &self.moniker
61    }
62
63    /// Return a pointer to the Job.
64    pub fn copy_job(&self) -> Arc<Job> {
65        self.job.clone()
66    }
67
68    pub fn get_outgoing_directory(&self) -> Option<&ClientEnd<fio::DirectoryMarker>> {
69        self.outgoing_directory_for_memory_attribution.as_ref()
70    }
71
72    pub fn get_program_config(&self) -> &ElfProgramConfig {
73        &self.program_config
74    }
75
76    /// Return a handle to the Job containing the process for this component.
77    ///
78    /// The rights of the job will be set such that the resulting handle will be appropriate to
79    /// use for diagnostics-only purposes. Right now that is ZX_RIGHTS_BASIC (which includes
80    /// INSPECT).
81    pub fn copy_job_for_diagnostics(&self) -> Result<zx::Job, zx::Status> {
82        self.job.top().duplicate_handle(zx::Rights::BASIC)
83    }
84
85    pub fn copy_instance_token(&self) -> Result<zx::Event, zx::Status> {
86        self.component_instance.duplicate_handle(zx::Rights::SAME_RIGHTS)
87    }
88}
89
90/// Structure representing a running elf component.
91pub struct ElfComponent {
92    /// Namespace directory for this component, kept just as a reference to
93    /// keep the namespace alive.
94    _runtime_dir: RuntimeDirectory,
95
96    /// Immutable information about the component.
97    info: Arc<ElfComponentInfo>,
98
99    /// Process made for the program binary defined for this component.
100    process: Option<Arc<Process>>,
101
102    /// Client end of the channel given to an ElfComponent which says it
103    /// implements the Lifecycle protocol. If the component does not implement
104    /// the protocol, this will be None.
105    lifecycle_channel: Option<LifecycleProxy>,
106
107    /// Any tasks spawned to serve this component. For example, stdout and stderr
108    /// listeners are Task objects that live for the duration of the component's
109    /// lifetime.
110    ///
111    /// Stop will block on these to complete.
112    tasks: Option<Vec<fasync::Task<()>>>,
113
114    /// A closure to be invoked when the object is dropped.
115    on_drop: Mutex<Option<Box<dyn FnOnce(&ElfComponentInfo) + Send + 'static>>>,
116}
117
118impl ElfComponent {
119    pub fn new(
120        _runtime_dir: RuntimeDirectory,
121        moniker: Moniker,
122        job: Job,
123        process: Process,
124        lifecycle_channel: Option<LifecycleProxy>,
125        main_process_critical: bool,
126        tasks: Vec<fasync::Task<()>>,
127        component_url: String,
128        outgoing_directory: Option<ClientEnd<fio::DirectoryMarker>>,
129        program_config: ElfProgramConfig,
130        component_instance: zx::Event,
131    ) -> Self {
132        Self {
133            _runtime_dir,
134            info: Arc::new(ElfComponentInfo {
135                moniker,
136                component_instance,
137                job: Arc::new(job),
138                main_process_critical,
139                component_url,
140                outgoing_directory_for_memory_attribution: outgoing_directory,
141                program_config,
142            }),
143            process: Some(Arc::new(process)),
144            lifecycle_channel,
145            tasks: Some(tasks),
146            on_drop: Mutex::new(None),
147        }
148    }
149
150    /// Sets a closure to be invoked when the object is dropped. Can only be done once.
151    pub fn set_on_drop(&self, func: impl FnOnce(&ElfComponentInfo) + Send + 'static) {
152        let mut on_drop = self.on_drop.lock().unwrap();
153        let previous = std::mem::replace(
154            on_drop.deref_mut(),
155            Some(Box::new(func) as Box<dyn FnOnce(&ElfComponentInfo) + Send + 'static>),
156        );
157        assert!(previous.is_none());
158    }
159
160    /// Obtain immutable information about the component such as its job and URL.
161    pub fn info(&self) -> &Arc<ElfComponentInfo> {
162        &self.info
163    }
164
165    /// Return a pointer to the Process, returns None if the component has no
166    /// Process.
167    pub fn copy_process(&self) -> Option<Arc<Process>> {
168        self.process.clone()
169    }
170}
171
172#[async_trait]
173impl Controllable for ElfComponent {
174    async fn kill(&mut self) {
175        if self.info().main_process_critical {
176            warn!("killing a component with 'main_process_critical', so this will also kill component_manager and all of its components");
177        }
178        self.info()
179            .job
180            .top()
181            .kill()
182            .unwrap_or_else(|error| error!(error:%; "failed killing job during kill"));
183    }
184
185    fn stop<'a>(&mut self) -> BoxFuture<'a, ()> {
186        if let Some(lifecycle_chan) = self.lifecycle_channel.take() {
187            lifecycle_chan.stop().unwrap_or_else(
188                |error| error!(error:%; "failed to stop lifecycle_chan during stop"),
189            );
190
191            let job = self.info().job.clone();
192
193            // If the component's main process is critical we must watch for
194            // the main process to exit, otherwise we could end up killing that
195            // process and therefore killing the root job.
196            if self.info().main_process_critical {
197                if self.process.is_none() {
198                    // This is a bit strange because there's no process, but there is a lifecycle
199                    // channel. Since there is no process it seems like killing it can't kill
200                    // component manager.
201                    warn!("killing job of component with 'main_process_critical' set because component has lifecycle channel, but no process main process.");
202                    self.info().job.top().kill().unwrap_or_else(|error| {
203                        error!(error:%; "failed killing job for component with no lifecycle channel")
204                    });
205                    return async {}.boxed();
206                }
207                // Try to duplicate the Process handle so we can us it to wait for
208                // process termination
209                let proc_handle = self.process.take().unwrap();
210
211                async move {
212                    fasync::OnSignals::new(
213                        &proc_handle.as_handle_ref(),
214                        zx::Signals::PROCESS_TERMINATED,
215                    )
216                    .await
217                    .map(|_: fidl::Signals| ()) // Discard.
218                    .unwrap_or_else(|e| {
219                        error!(
220                            "killing component's job after failure waiting on process exit, err: {}",
221                            e
222                        )
223                    });
224                    job.top().kill().unwrap_or_else(|error| {
225                        error!(error:%; "failed killing job in stop after lifecycle channel closed")
226                    });
227                }
228                .boxed()
229            } else {
230                async move {
231                    lifecycle_chan.on_closed()
232                    .await
233                    .map(|_: fidl::Signals| ())  // Discard.
234                    .unwrap_or_else(|e| {
235                        error!(
236                        "killing component's job after failure waiting on lifecycle channel, err: {}",
237                        e
238                        )
239                    });
240                    job.top().kill().unwrap_or_else(|error| {
241                        error!(error:%; "failed killing job in stop after lifecycle channel closed")
242                    });
243                }
244                .boxed()
245            }
246        } else {
247            if self.info().main_process_critical {
248                warn!(
249                    "killing job of component {} marked with 'main_process_critical' because \
250                component does not implement Lifecycle, so this will also kill component_manager \
251                and all of its components",
252                    self.info().get_url()
253                );
254            }
255            self.info().job.top().kill().unwrap_or_else(|error| {
256                error!(error:%; "failed killing job for component with no lifecycle channel")
257            });
258            async {}.boxed()
259        }
260    }
261
262    fn teardown<'a>(&mut self) -> BoxFuture<'a, ()> {
263        let tasks = self.tasks.take().unwrap_or_default();
264        async move {
265            join_all(tasks).await;
266        }
267        .boxed()
268    }
269
270    fn on_escrow<'a>(&self) -> BoxStream<'a, ComponentControllerOnEscrowRequest> {
271        let Some(lifecycle) = &self.lifecycle_channel else {
272            return futures::stream::empty().boxed();
273        };
274        lifecycle
275            .take_event_stream()
276            .filter_map(|result| async {
277                match result {
278                    Ok(LifecycleEvent::OnEscrow { payload }) => {
279                        Some(ComponentControllerOnEscrowRequest {
280                            outgoing_dir: payload.outgoing_dir,
281                            escrowed_dictionary: payload.escrowed_dictionary,
282                            ..Default::default()
283                        })
284                    }
285                    Err(fidl::Error::ClientChannelClosed { .. }) => {
286                        // The ELF program is expected to close the server endpoint.
287                        None
288                    }
289                    Err(error) => {
290                        warn!(error:%; "error handling lifecycle channel events");
291                        None
292                    }
293                }
294            })
295            .boxed()
296    }
297}
298
299impl Drop for ElfComponent {
300    fn drop(&mut self) {
301        // notify others that this object is being dropped
302        if let Some(on_drop) = self.on_drop.lock().unwrap().take() {
303            on_drop(self.info().as_ref());
304        }
305        // just in case we haven't killed the job already
306        self.info()
307            .job
308            .top()
309            .kill()
310            .unwrap_or_else(|error| error!(error:%; "failed to kill job in drop"));
311    }
312}
elf_runner/component.rs

elf_runner/
component.rs
