From 8d0ac9bdc852802fb034d2b72cde79094f673222 Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Mon, 28 Nov 2022 13:16:58 -0500
Subject: [PATCH] ptmgr: Mark PtMessage and next_message as experimental-api.

These are implementation details and we don't want to mark them as
stable.

To do this, I needed to apply some additional options to the example
code's configuration in Cargo.toml.
---
 Cargo.lock                  |  1 +
 crates/tor-ptmgr/Cargo.toml |  8 ++++++++
 crates/tor-ptmgr/README.md  | 14 ++++++++++++++
 crates/tor-ptmgr/src/ipc.rs |  7 ++++---
 4 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1a84bb1a5..bcd4e3b23 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4085,6 +4085,7 @@ dependencies = [
  "tor-socksproto",
  "tracing",
  "tracing-subscriber",
+ "visibility",
 ]
 
 [[package]]
diff --git a/crates/tor-ptmgr/Cargo.toml b/crates/tor-ptmgr/Cargo.toml
index c4b418d7c..77b098e80 100644
--- a/crates/tor-ptmgr/Cargo.toml
+++ b/crates/tor-ptmgr/Cargo.toml
@@ -15,6 +15,9 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
 default = ["tor-channel-factory"]
 tor-channel-factory = []
 
+experimental = ["experimental-api"]
+experimental-api = ["visibility"]
+
 [dependencies]
 async-trait = "0.1.2"
 derive_builder = { version = "0.11.2", package = "derive_builder_fork_arti" }
@@ -29,6 +32,7 @@ tor-linkspec = { version = "0.5.1", path = "../tor-linkspec", features = ["pt-cl
 tor-rtcompat = { version = "0.7.0", path = "../tor-rtcompat" }
 tor-socksproto = { version = "0.5.1", path = "../tor-socksproto" }
 tracing = "0.1.18"
+visibility = { version = "0.0.1", optional = true }
 
 [dev-dependencies]
 anyhow = "1.0.23"
@@ -42,3 +46,7 @@ tokio = { version = "1.7", features = [
 ] }
 tor-rtcompat = { path = "../tor-rtcompat", version = "0.7.0", features = ["tokio", "native-tls"] }
 tracing-subscriber = "0.3.0"
+
+[[example]]
+name = "run-pt"
+required-features = ["experimental-api"]
diff --git a/crates/tor-ptmgr/README.md b/crates/tor-ptmgr/README.md
index 1da2f091b..035ee8d37 100644
--- a/crates/tor-ptmgr/README.md
+++ b/crates/tor-ptmgr/README.md
@@ -35,4 +35,18 @@ TODO pt-client: The first version of this crate will probably only conform
 to the old Tor pluggable transport protocol, and not to more recent variants
 as documented at `pluggabletransports.info`
 
+## Feature flags
+
+### Experimental and unstable features
+
+ Note that the APIs enabled by these features are NOT covered by semantic
+ versioning guarantees: we might break them or remove them between patch
+ versions.
+
+* `experimental-api` -- build with experimental, unstable API support.
+
+* `experimental` -- Build with all experimental features above, along with
+  all experimental features from other arti crates.
+
+
 License: MIT OR Apache-2.0
diff --git a/crates/tor-ptmgr/src/ipc.rs b/crates/tor-ptmgr/src/ipc.rs
index 435ecf7bf..0d05b9a29 100644
--- a/crates/tor-ptmgr/src/ipc.rs
+++ b/crates/tor-ptmgr/src/ipc.rs
@@ -47,10 +47,10 @@ pub struct PtStatus {
 /// A message sent from a pluggable transport child process.
 ///
 /// For more in-depth information about these messages, consult pt-spec.txt.
-// TODO pt-client: this shouldn't be `pub`
 #[derive(PartialEq, Eq, Debug, Clone)]
 #[non_exhaustive]
-pub enum PtMessage {
+#[cfg_attr(feature = "experimental-api", visibility::make(pub))]
+pub(crate) enum PtMessage {
     /// `VERSION-ERROR`: No compatible pluggable transport specification version was provided.
     VersionError(String),
     /// `VERSION`: Specifies the version the binary is using for the IPC protocol.
@@ -600,7 +600,8 @@ impl PluggableTransport {
     // FIXME(eta): This API will probably go away and get replaced with something better.
     //             In particular, we'd want to cache `Status` messages from before this method
     //             was called.
-    pub async fn next_message(&mut self) -> err::Result<PtMessage> {
+    #[cfg_attr(feature = "experimental-api", visibility::make(pub))]
+    pub(crate) async fn next_message(&mut self) -> err::Result<PtMessage> {
         let inner = self.inner.as_mut().ok_or(PtError::ChildGone)?;
         let ret = inner.recv().await;
         if let Err(PtError::ChildGone) | Err(PtError::ChildReadFailed { .. }) = ret {