1#[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#[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 NoContainer = 1,
73 ContainerCreated = 2,
75 ContainerStarting = 3,
77 ContainerStopped = 4,
79 NotLoggedIn = 5,
81 Ready = 6,
83 Unknown = 7,
85}
86
87#[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 config: DockerizedIBGatewayConfig,
109 pub(crate) docker: Docker,
111 username: SecretString,
113 password: SecretString,
115 host: String,
117 port: u16,
119 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 pub const CONTAINER_NAME: &'static str = "nautilus-ib-gateway";
139
140 pub const HOST_PORTS: &'static [(&'static str, u16)] = &[("Paper", 4002), ("Live", 4001)];
142
143 pub const CONTAINER_PORTS: &'static [(&'static str, u16)] = &[("Paper", 4004), ("Live", 4003)];
145
146 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 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 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 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 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 pub fn container_name(&self) -> &str {
234 &self.container_name
235 }
236
237 pub fn host(&self) -> &str {
239 &self.host
240 }
241
242 pub fn port(&self) -> u16 {
244 self.port
245 }
246
247 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 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 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 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 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 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 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 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 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 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 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 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 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#[cfg(not(feature = "gateway"))]
547#[derive(Debug)]
548pub struct DockerizedIBGateway;
549
550#[cfg(not(feature = "gateway"))]
551impl DockerizedIBGateway {
552 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}