pdk-test 1.7.0

PDK Test
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

// Copyright (c) 2026, Salesforce, Inc.,
// All rights reserved.
// For full license text, see the LICENSE.txt file

//! Docker network port management
//!
//! This module provides types and utilities for handling Docker network ports
//! with different visibility modes. It supports both exposed and published ports
//! for container networking in test environments.
//!
//! ## Primary types
//!
//! - [`Port`]: network port type alias for u16
//! - [`PortVisibility`]: enum for port visibility modes (Exposed/Published)
//! - [`PortAccess`]: struct for port configuration and access control
//!

use crate::portpicker;

/// Represents a network port.
pub type Port = u16;

/// Visility of a port inside a Docker network.
#[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
pub enum PortVisibility {
    /// Represents visibility for exposed ports.
    /// In Docker terminology, an exposed port is visible just inside
    /// Docker networks without matching the same port number in the host machine.
    #[default]
    Exposed,

    /// Represents visibility for published ports.
    /// In Docker terminology, a published port is visible for
    /// Docker networks and matches the same port number in the host machine.
    Published,
}

impl PortVisibility {
    /// Returns [`true`] if the visibility is [`PortVisibility::Exposed`].
    pub fn is_exposed(&self) -> bool {
        matches!(*self, PortVisibility::Exposed)
    }

    /// Returns [`true`] if the visibility is [`PortVisibility::Published`].
    pub fn is_published(&self) -> bool {
        matches!(*self, PortVisibility::Published)
    }
}

/// A type representing the port access inside a Docker network.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PortAccess {
    port: Port,
    public_port: Option<Port>,
    visibility: PortVisibility,
}

impl PortAccess {
    /// Create a new [`PortAccess`] for a given port and visibility.
    pub const fn new(port: Port, visibility: PortVisibility) -> Self {
        Self {
            port,
            public_port: None,
            visibility,
        }
    }

    /// Creates a [`PortAccess`] for a `port` with exposed visibility.
    pub const fn exposed(port: Port) -> Self {
        Self {
            port,
            public_port: None,
            visibility: PortVisibility::Exposed,
        }
    }

    /// Creates a [`PortAccess`] for a `port` with published visibility.
    pub const fn published(port: Port) -> Self {
        Self {
            port,
            public_port: None,
            visibility: PortVisibility::Published,
        }
    }

    /// Create a new [`PortAccess`] for a given port and fixed public port.
    pub(crate) const fn published_with_fixed_public_port(port: Port, public_port: Port) -> Self {
        Self {
            port,
            public_port: Some(public_port),
            visibility: PortVisibility::Published,
        }
    }

    /// Returns the port.
    pub const fn port(&self) -> Port {
        self.port
    }

    /// Defines the public port for the given internal port of the container. If the given
    /// [PortAccess](PortAccess) already provides one, it is used. Otherwise, a free port is picked
    /// from the OS
    pub(crate) fn public_port(&self) -> Option<Port> {
        match self.visibility {
            PortVisibility::Exposed => None,
            PortVisibility::Published => self.public_port.or_else(portpicker::pick_unused_port),
        }
    }

    /// Returns the visibility.
    pub const fn visibility(&self) -> PortVisibility {
        self.visibility
    }
}