Skip to main content

nautilus_interactive_brokers/gateway/
dockerized.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
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
16//! Dockerized IB Gateway management.
17
18#[cfg(feature = "gateway")]
19use std::{collections::HashMap, fmt::Debug};
20
21#[cfg(feature = "gateway")]
22use anyhow::Context;
23#[cfg(feature = "gateway")]
24use bollard::Docker;
25#[cfg(feature = "gateway")]
26use bollard::container::LogOutput;
27#[cfg(feature = "gateway")]
28use bollard::errors::Error as DockerError;
29#[cfg(feature = "gateway")]
30use bollard::models::{
31    ContainerCreateBody, ContainerCreateResponse, HostConfig, PortBinding, RestartPolicy,
32    RestartPolicyNameEnum,
33};
34#[cfg(feature = "gateway")]
35use bollard::query_parameters::{
36    CreateContainerOptions, ListContainersOptions, LogsOptions, RemoveContainerOptions,
37    StartContainerOptions, StopContainerOptions,
38};
39#[cfg(feature = "gateway")]
40use futures_util::StreamExt;
41#[cfg(feature = "gateway")]
42use jiff::Timestamp;
43#[cfg(feature = "gateway")]
44use nautilus_core::string::secret::SecretString;
45use serde::{Deserialize, Serialize};
46
47#[cfg(feature = "gateway")]
48use super::startup::{self, GatewayContainer};
49#[cfg(not(feature = "gateway"))]
50use crate::config::DockerizedIBGatewayConfig;
51#[cfg(feature = "gateway")]
52use crate::config::{DockerizedIBGatewayConfig, TradingMode};
53
54/// Container status enumeration.
55#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
56#[cfg_attr(
57    feature = "python",
58    pyo3::pyclass(
59        module = "nautilus_trader.adapters.interactive_brokers",
60        from_py_object,
61        rename_all = "SCREAMING_SNAKE_CASE"
62    )
63)]
64#[cfg_attr(
65    feature = "python",
66    pyo3_stub_gen::derive::gen_stub_pyclass_enum(
67        module = "nautilus_trader.adapters.interactive_brokers"
68    )
69)]
70pub enum ContainerStatus {
71    /// No container exists.
72    NoContainer = 1,
73    /// Container has been created but not started.
74    ContainerCreated = 2,
75    /// Container is starting.
76    ContainerStarting = 3,
77    /// Container has stopped.
78    ContainerStopped = 4,
79    /// Container is running but not logged in.
80    NotLoggedIn = 5,
81    /// Container is ready (running and logged in).
82    Ready = 6,
83    /// Unknown container status.
84    Unknown = 7,
85}
86
87/// Dockerized IB Gateway manager.
88///
89/// This struct manages the lifecycle of Interactive Brokers Gateway Docker containers,
90/// including creation, starting, stopping, and status checking.
91#[derive(Clone)]
92#[cfg_attr(
93    feature = "python",
94    pyo3::pyclass(
95        module = "nautilus_trader.adapters.interactive_brokers",
96        from_py_object
97    )
98)]
99#[cfg_attr(
100    feature = "python",
101    pyo3_stub_gen::derive::gen_stub_pyclass(
102        module = "nautilus_trader.adapters.interactive_brokers"
103    )
104)]
105#[cfg(feature = "gateway")]
106pub struct DockerizedIBGateway {
107    /// Configuration for the gateway.
108    config: DockerizedIBGatewayConfig,
109    /// Docker client.
110    pub(crate) docker: Docker,
111    /// Username for IB account.
112    username: SecretString,
113    /// Password for IB account.
114    password: SecretString,
115    /// Host address (always 127.0.0.1).
116    host: String,
117    /// Port for the gateway.
118    port: u16,
119    /// Container name.
120    container_name: String,
121}
122
123#[cfg(feature = "gateway")]
124impl Debug for DockerizedIBGateway {
125    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
126        f.debug_struct(stringify!(DockerizedIBGateway))
127            .field("host", &self.host)
128            .field("port", &self.port)
129            .field("container_name", &self.container_name)
130            .field("trading_mode", &self.config.trading_mode)
131            .finish_non_exhaustive()
132    }
133}
134
135#[cfg(feature = "gateway")]
136impl DockerizedIBGateway {
137    /// Base container name.
138    pub const CONTAINER_NAME: &'static str = "nautilus-ib-gateway";
139
140    /// Host API ports by trading mode.
141    pub const HOST_PORTS: &'static [(&'static str, u16)] = &[("Paper", 4002), ("Live", 4001)];
142
143    /// Container API ports exposed by the IB Gateway image.
144    pub const CONTAINER_PORTS: &'static [(&'static str, u16)] = &[("Paper", 4004), ("Live", 4003)];
145
146    /// Internal VNC port.
147    pub const VNC_PORT_INTERNAL: u16 = 5900;
148
149    fn host_port_for_mode(trading_mode: TradingMode) -> u16 {
150        match trading_mode {
151            TradingMode::Paper => 4002,
152            TradingMode::Live => 4001,
153        }
154    }
155
156    fn container_port_for_mode(trading_mode: TradingMode) -> u16 {
157        match trading_mode {
158            TradingMode::Paper => 4004,
159            TradingMode::Live => 4003,
160        }
161    }
162
163    fn logs_indicate_ready(logs: &str) -> bool {
164        logs.contains("Login has completed")
165            || logs.contains("Configuration tasks completed")
166            || logs.contains("Logged in to")
167            || logs.contains("Login successful")
168    }
169
170    fn session_logs_indicate_ready(logs: &str, started_at: Timestamp) -> bool {
171        logs.lines().any(|line| {
172            let Some((timestamp, message)) = line.split_once(' ') else {
173                return false;
174            };
175
176            timestamp.parse::<Timestamp>().is_ok_and(|timestamp| {
177                timestamp >= started_at && Self::logs_indicate_ready(message)
178            })
179        })
180    }
181
182    /// Create a new DockerizedIBGateway from configuration.
183    ///
184    /// # Errors
185    ///
186    /// Returns an error if:
187    /// - Configuration validation fails.
188    /// - Username or password is not provided and not available in environment variables.
189    /// - Docker client creation fails.
190    pub fn new(mut config: DockerizedIBGatewayConfig) -> anyhow::Result<Self> {
191        config.validate()?;
192
193        let username = config
194            .username
195            .take()
196            .or_else(|| std::env::var("TWS_USERNAME").ok().map(SecretString::from))
197            .ok_or_else(|| anyhow::anyhow!("username not set nor available in env TWS_USERNAME"))?;
198
199        let password = config
200            .password
201            .take()
202            .or_else(|| std::env::var("TWS_PASSWORD").ok().map(SecretString::from))
203            .ok_or_else(|| anyhow::anyhow!("password not set nor available in env TWS_PASSWORD"))?;
204
205        // Connect to Docker
206        let docker = Docker::connect_with_local_defaults().context(
207            "Failed to connect to the local Docker daemon. Ensure Docker is running and the local Docker socket is available",
208        )?;
209
210        // Determine port based on trading mode
211        let mode_str = match config.trading_mode {
212            TradingMode::Paper => "Paper",
213            TradingMode::Live => "Live",
214        };
215
216        let port = Self::host_port_for_mode(config.trading_mode);
217
218        // Generate container name
219        let container_name = format!("{}-{}", Self::CONTAINER_NAME, mode_str).to_lowercase();
220
221        Ok(Self {
222            config,
223            docker,
224            username,
225            password,
226            host: "127.0.0.1".to_string(),
227            port,
228            container_name,
229        })
230    }
231
232    /// Get the container name.
233    pub fn container_name(&self) -> &str {
234        &self.container_name
235    }
236
237    /// Get the host address.
238    pub fn host(&self) -> &str {
239        &self.host
240    }
241
242    /// Get the port.
243    pub fn port(&self) -> u16 {
244        self.port
245    }
246
247    /// Check if the container is logged in by examining logs.
248    ///
249    /// # Errors
250    ///
251    /// Returns an error if log retrieval fails.
252    pub async fn is_logged_in(&self, container_id: &str) -> anyhow::Result<bool> {
253        let started_at = self
254            .docker
255            .inspect_container(container_id, None)
256            .await
257            .context("Failed to inspect gateway container")?
258            .state
259            .and_then(|state| state.started_at)
260            .context("Gateway container start time is missing")?
261            .parse::<Timestamp>()
262            .context("Gateway container start time is invalid")?;
263        let since = i32::try_from(started_at.as_second())
264            .context("Gateway container start time exceeds the Docker log API range")?;
265
266        let logs_options = LogsOptions {
267            stdout: true,
268            stderr: true,
269            since,
270            timestamps: true,
271            ..Default::default()
272        };
273
274        let mut logs_stream = self.docker.logs(container_id, Some(logs_options));
275
276        let mut logged_in = false;
277
278        while let Some(log_result) = logs_stream.next().await {
279            let log_output = log_result.context("Failed to read log chunk")?;
280
281            // Handle LogOutput enum variants
282            let log_bytes = match log_output {
283                LogOutput::StdOut { message } | LogOutput::StdErr { message } => message,
284                LogOutput::StdIn { message } | LogOutput::Console { message } => message,
285            };
286
287            let log_string = String::from_utf8_lossy(&log_bytes);
288            if Self::session_logs_indicate_ready(&log_string, started_at) {
289                logged_in = true;
290                break;
291            }
292        }
293
294        Ok(logged_in)
295    }
296
297    /// Get the current container status.
298    ///
299    /// # Errors
300    ///
301    /// Returns an error if container inspection fails.
302    pub async fn container_status(&self) -> anyhow::Result<ContainerStatus> {
303        let list_options = ListContainersOptions {
304            all: true,
305            ..Default::default()
306        };
307
308        let containers = self
309            .docker
310            .list_containers(Some(list_options))
311            .await
312            .context("Failed to list containers")?;
313
314        let container = containers.iter().find(|c| {
315            c.names
316                .as_ref()
317                .and_then(|names| names.first())
318                .is_some_and(|name| name.trim_start_matches('/') == self.container_name)
319        });
320
321        let Some(container) = container else {
322            return Ok(ContainerStatus::NoContainer);
323        };
324
325        let state = container
326            .state
327            .as_ref()
328            .map_or("unknown", |state| state.as_ref());
329
330        match state {
331            "running" => {
332                let container_id = container
333                    .id
334                    .as_ref()
335                    .ok_or_else(|| anyhow::anyhow!("Container ID missing"))?;
336
337                if self.is_logged_in(container_id).await.unwrap_or(false) {
338                    Ok(ContainerStatus::Ready)
339                } else {
340                    Ok(ContainerStatus::ContainerStarting)
341                }
342            }
343            "stopped" | "exited" => Ok(ContainerStatus::ContainerStopped),
344            "created" => Ok(ContainerStatus::ContainerCreated),
345            _ => Ok(ContainerStatus::Unknown),
346        }
347    }
348
349    /// Starts the gateway container, or reuses a running one, and waits for its login.
350    ///
351    /// Waits up to `wait` seconds, or the configured timeout without one.
352    ///
353    /// # Errors
354    ///
355    /// Returns an error if:
356    /// - Container creation or startup fails.
357    /// - The gateway does not log in within the wait.
358    pub async fn start(&mut self, wait: Option<u64>) -> anyhow::Result<()> {
359        startup::start(&*self, wait.unwrap_or(self.config.timeout)).await
360    }
361
362    /// Starts the gateway like [`Self::start`], and waits for the login of a container that
363    /// another caller has just created.
364    ///
365    /// # Errors
366    ///
367    /// Returns an error if:
368    /// - Startup fails for a reason other than that conflict.
369    /// - The gateway does not log in within the wait.
370    pub async fn safe_start(&mut self, wait: Option<u64>) -> anyhow::Result<()> {
371        startup::safe_start(&*self, wait.unwrap_or(self.config.timeout)).await
372    }
373
374    /// Stop and remove the gateway container.
375    ///
376    /// # Errors
377    ///
378    /// Returns an error if container stop or removal fails.
379    pub async fn stop(&self) -> anyhow::Result<()> {
380        let list_options = ListContainersOptions {
381            all: true,
382            ..Default::default()
383        };
384
385        let containers = self
386            .docker
387            .list_containers(Some(list_options))
388            .await
389            .context("Failed to list containers")?;
390
391        let container = containers.iter().find(|c| {
392            c.names
393                .as_ref()
394                .and_then(|names| names.first())
395                .is_some_and(|name| name.trim_start_matches('/') == self.container_name)
396        });
397
398        if let Some(container) = container
399            && let Some(container_id) = &container.id
400        {
401            // Stop container if running
402            if matches!(
403                container.state.as_ref().map(|state| state.as_ref()),
404                Some("running")
405            ) {
406                self.docker
407                    .stop_container(container_id, None::<StopContainerOptions>)
408                    .await
409                    .context("Failed to stop container")?;
410            }
411
412            // Remove container
413            let remove_options = RemoveContainerOptions {
414                force: true,
415                ..Default::default()
416            };
417
418            self.docker
419                .remove_container(container_id, Some(remove_options))
420                .await
421                .context("Failed to remove container")?;
422
423            tracing::debug!("Stopped and removed container `{}`", self.container_name);
424        }
425
426        Ok(())
427    }
428}
429
430#[cfg(feature = "gateway")]
431impl GatewayContainer for DockerizedIBGateway {
432    fn name(&self) -> &str {
433        &self.container_name
434    }
435
436    fn is_conflict(error: &anyhow::Error) -> bool {
437        matches!(
438            error.downcast_ref(),
439            Some(DockerError::DockerResponseServerError {
440                status_code: 409,
441                ..
442            })
443        )
444    }
445
446    async fn status(&self) -> anyhow::Result<ContainerStatus> {
447        self.container_status().await
448    }
449
450    async fn remove(&self) -> anyhow::Result<()> {
451        self.stop().await
452    }
453
454    async fn create(&self) -> anyhow::Result<()> {
455        // Determine port mappings
456        let host_port = Self::host_port_for_mode(self.config.trading_mode);
457        let container_port = Self::container_port_for_mode(self.config.trading_mode);
458
459        let mut port_bindings = HashMap::new();
460        port_bindings.insert(
461            format!("{container_port}/tcp"),
462            Some(vec![PortBinding {
463                host_ip: Some(self.host.clone()),
464                host_port: Some(host_port.to_string()),
465            }]),
466        );
467
468        if let Some(vnc_port) = self.config.vnc_port {
469            port_bindings.insert(
470                format!("{}/tcp", Self::VNC_PORT_INTERNAL),
471                Some(vec![PortBinding {
472                    host_ip: Some(self.host.clone()),
473                    host_port: Some(vnc_port.to_string()),
474                }]),
475            );
476        }
477
478        // Prepare environment variables
479        let mode_str = match self.config.trading_mode {
480            TradingMode::Paper => "paper",
481            TradingMode::Live => "live",
482        };
483
484        let env = vec![
485            format!("TWS_USERID={}", self.username.expose_secret()),
486            format!("TWS_PASSWORD={}", self.password.expose_secret()),
487            format!("TRADING_MODE={}", mode_str),
488            format!(
489                "READ_ONLY_API={}",
490                if self.config.read_only_api {
491                    "yes"
492                } else {
493                    "no"
494                }
495            ),
496            "EXISTING_SESSION_DETECTED_ACTION=primary".to_string(),
497        ];
498
499        // Create container configuration
500        let container_config = ContainerCreateBody {
501            image: Some(self.config.container_image.clone()),
502            hostname: Some(self.container_name.clone()),
503            host_config: Some(HostConfig {
504                port_bindings: Some(port_bindings),
505                restart_policy: Some(RestartPolicy {
506                    name: Some(RestartPolicyNameEnum::ALWAYS),
507                    maximum_retry_count: None,
508                }),
509                ..Default::default()
510            }),
511            env: Some(env),
512            ..Default::default()
513        };
514
515        // Create container
516        let create_options = CreateContainerOptions {
517            name: Some(self.container_name.clone()),
518            ..Default::default()
519        };
520
521        let create_response: ContainerCreateResponse = self
522            .docker
523            .create_container(Some(create_options), container_config)
524            .await
525            .context("Failed to create container")?;
526
527        let container_id = create_response.id;
528
529        // Start container
530        self.docker
531            .start_container(&container_id, None::<StartContainerOptions>)
532            .await
533            .context("Failed to start container")?;
534
535        tracing::debug!(
536            "Container `{}` starting, waiting for ready. VNC port is {:?}",
537            self.container_name,
538            self.config.vnc_port
539        );
540
541        Ok(())
542    }
543}
544
545/// Stub implementation when gateway feature is disabled.
546#[cfg(not(feature = "gateway"))]
547#[derive(Debug)]
548pub struct DockerizedIBGateway;
549
550#[cfg(not(feature = "gateway"))]
551impl DockerizedIBGateway {
552    /// # Errors
553    ///
554    /// Returns an error if the Dockerized IB Gateway cannot be created or started.
555    pub fn new(_config: DockerizedIBGatewayConfig) -> anyhow::Result<Self> {
556        anyhow::bail!("Gateway feature is not enabled. Build with --features gateway")
557    }
558}
559
560#[cfg(all(test, feature = "gateway"))]
561mod tests {
562    use jiff::Timestamp;
563    use nautilus_core::string::secret::SecretString;
564    use rstest::rstest;
565
566    use super::{DockerError, DockerizedIBGateway, GatewayContainer};
567    use crate::config::{DockerizedIBGatewayConfig, TradingMode};
568
569    #[rstest]
570    #[case::timeout_zero(0, None, "Timeout must be greater than 0")]
571    #[case::timeout_high(3601, None, "Timeout must be less than 3600 seconds")]
572    #[case::vnc_port(300, Some(5899), "VNC port must be between 5900 and 5999")]
573    fn test_constructor_rejects_invalid_config(
574        #[case] timeout: u64,
575        #[case] vnc_port: Option<u16>,
576        #[case] expected: &str,
577    ) {
578        let config = DockerizedIBGatewayConfig {
579            username: None,
580            password: None,
581            timeout,
582            vnc_port,
583            ..Default::default()
584        };
585
586        let error = DockerizedIBGateway::new(config).unwrap_err();
587
588        assert_eq!(error.to_string(), expected);
589    }
590
591    #[rstest]
592    #[case(TradingMode::Paper, 4002)]
593    #[case(TradingMode::Live, 4001)]
594    fn host_port_matches_trading_mode(#[case] trading_mode: TradingMode, #[case] expected: u16) {
595        assert_eq!(
596            DockerizedIBGateway::host_port_for_mode(trading_mode),
597            expected
598        );
599    }
600
601    #[rstest]
602    #[case(TradingMode::Paper, 4004)]
603    #[case(TradingMode::Live, 4003)]
604    fn container_port_matches_trading_mode(
605        #[case] trading_mode: TradingMode,
606        #[case] expected: u16,
607    ) {
608        assert_eq!(
609            DockerizedIBGateway::container_port_for_mode(trading_mode),
610            expected
611        );
612    }
613
614    #[rstest]
615    #[case(TradingMode::Paper, 4002)]
616    #[case(TradingMode::Live, 4001)]
617    fn new_reports_the_host_api_port(#[case] trading_mode: TradingMode, #[case] expected: u16) {
618        let gateway = DockerizedIBGateway::new(
619            DockerizedIBGatewayConfig::builder()
620                .username(SecretString::from("test-user"))
621                .password(SecretString::from("test-password"))
622                .trading_mode(trading_mode)
623                .build(),
624        )
625        .unwrap();
626
627        assert_eq!(gateway.port(), expected);
628        assert_eq!(gateway.username.expose_secret(), "test-user");
629        assert_eq!(gateway.password.expose_secret(), "test-password");
630        assert!(gateway.config.username.is_none());
631        assert!(gateway.config.password.is_none());
632    }
633
634    #[rstest]
635    #[case(409, true)]
636    #[case(404, false)]
637    fn conflict_is_found_through_context(#[case] status_code: u16, #[case] expected: bool) {
638        let error = anyhow::Error::new(DockerError::DockerResponseServerError {
639            status_code,
640            message: "the container name is already in use".to_string(),
641        })
642        .context("Failed to create container");
643
644        assert_eq!(DockerizedIBGateway::is_conflict(&error), expected);
645    }
646
647    #[rstest]
648    #[case("Forking ::: Starting IBC Gateway", false)]
649    #[case("Started IB Gateway", false)]
650    #[case("Login has completed", true)]
651    #[case("Configuration tasks completed", true)]
652    #[case("Logged in to backend", true)]
653    #[case("Login successful", true)]
654    fn ready_log_markers_are_strict(#[case] logs: &str, #[case] expected: bool) {
655        assert_eq!(DockerizedIBGateway::logs_indicate_ready(logs), expected);
656    }
657
658    #[rstest]
659    #[case(
660        "2026-08-16T09:59:59Z Login has completed\n2026-08-16T10:00:01Z Started IB Gateway",
661        false
662    )]
663    #[case(
664        "2026-08-16T09:59:59Z Login has completed\n2026-08-16T10:00:01Z Login successful",
665        true
666    )]
667    #[case("2026-08-16T10:00:00Z Login has completed", true)]
668    fn readiness_uses_only_current_session_logs(#[case] logs: &str, #[case] expected: bool) {
669        let started_at = "2026-08-16T10:00:00Z".parse::<Timestamp>().unwrap();
670
671        assert_eq!(
672            DockerizedIBGateway::session_logs_indicate_ready(logs, started_at),
673            expected,
674        );
675    }
676}