Skip to content

Commit

Permalink
Add and update doc links for configuration options
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrobsonchase
jrobsonchase committed Nov 1, 2023
1 parent 55a640e commit cae525a
Show file tree
Hide file tree
Showing 7 changed files with 86 additions and 0 deletions.
40 changes: 40 additions & 0 deletions ngrok/src/config/http.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -209,16 +209,22 @@ impl From<(String, String)> for BasicAuthCredential {

impl_builder! {
/// A builder for a tunnel backing an HTTP endpoint.
///
/// https://ngrok.com/docs/http/
HttpTunnelBuilder, HttpOptions, HttpTunnel, endpoint
}

impl HttpTunnelBuilder {
/// Add the provided CIDR to the allowlist.
///
/// https://ngrok.com/docs/http/ip-restrictions/
pub fn allow_cidr(&mut self, cidr: impl Into<String>) -> &mut Self {
self.options.common_opts.cidr_restrictions.allow(cidr);
self
}
/// Add the provided CIDR to the denylist.
///
/// https://ngrok.com/docs/http/ip-restrictions/
pub fn deny_cidr(&mut self, cidr: impl Into<String>) -> &mut Self {
self.options.common_opts.cidr_restrictions.deny(cidr);
self
Expand All @@ -229,6 +235,8 @@ impl HttpTunnelBuilder {
self
}
/// Sets the opaque metadata string for this tunnel.
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn metadata(&mut self, metadata: impl Into<String>) -> &mut Self {
self.options.common_opts.metadata = Some(metadata.into());
self
Expand All @@ -239,6 +247,8 @@ impl HttpTunnelBuilder {
/// This overrides the default process info if using
/// [TunnelBuilder::listen], and is in turn overridden by the url provided
/// to [ForwarderBuilder::listen_and_forward].
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn forwards_to(&mut self, forwards_to: impl Into<String>) -> &mut Self {
self.options.common_opts.forwards_to = Some(forwards_to.into());
self
Expand All @@ -249,6 +259,8 @@ impl HttpTunnelBuilder {
self
}
/// Sets the domain to request for this edge.
///
/// https://ngrok.com/docs/network-edge/domains-and-tcp-addresses/#domains
pub fn domain(&mut self, domain: impl Into<String>) -> &mut Self {
self.options.domain = Some(domain.into());
self
Expand All @@ -257,22 +269,30 @@ impl HttpTunnelBuilder {
///
/// These will be used to authenticate client certificates for requests at
/// the ngrok edge.
///
/// https://ngrok.com/docs/http/mutual-tls/
pub fn mutual_tlsca(&mut self, mutual_tlsca: Bytes) -> &mut Self {
self.options.mutual_tlsca.push(mutual_tlsca);
self
}
/// Enables gzip compression.
///
/// https://ngrok.com/docs/http/compression/
pub fn compression(&mut self) -> &mut Self {
self.options.compression = true;
self
}
/// Enables the websocket-to-tcp converter.
///
/// https://ngrok.com/docs/http/websocket-tcp-converter/
pub fn websocket_tcp_conversion(&mut self) -> &mut Self {
self.options.websocket_tcp_conversion = true;
self
}
/// Sets the 5XX response ratio at which the ngrok edge will stop sending
/// requests to this tunnel.
///
/// https://ngrok.com/docs/http/circuit-breaker/
pub fn circuit_breaker(&mut self, circuit_breaker: f64) -> &mut Self {
self.options.circuit_breaker = circuit_breaker;
self
Expand All @@ -290,6 +310,8 @@ impl HttpTunnelBuilder {
}

/// Adds a header to all requests to this edge.
///
/// https://ngrok.com/docs/http/request-headers/
pub fn request_header(
&mut self,
name: impl Into<String>,
Expand All @@ -299,6 +321,8 @@ impl HttpTunnelBuilder {
self
}
/// Adds a header to all responses coming from this edge.
///
/// https://ngrok.com/docs/http/response-headers/
pub fn response_header(
&mut self,
name: impl Into<String>,
Expand All @@ -308,18 +332,24 @@ impl HttpTunnelBuilder {
self
}
/// Removes a header from requests to this edge.
///
/// https://ngrok.com/docs/http/request-headers/
pub fn remove_request_header(&mut self, name: impl Into<String>) -> &mut Self {
self.options.request_headers.remove(name);
self
}
/// Removes a header from responses from this edge.
///
/// https://ngrok.com/docs/http/response-headers/
pub fn remove_response_header(&mut self, name: impl Into<String>) -> &mut Self {
self.options.response_headers.remove(name);
self
}

/// Adds the provided credentials to the list of basic authentication
/// credentials.
///
/// https://ngrok.com/docs/http/basic-auth/
pub fn basic_auth(
&mut self,
username: impl Into<String>,
Expand All @@ -332,18 +362,24 @@ impl HttpTunnelBuilder {
}

/// Set the OAuth configuraton for this edge.
///
/// https://ngrok.com/docs/http/oauth/
pub fn oauth(&mut self, oauth: impl Borrow<OauthOptions>) -> &mut Self {
self.options.oauth = Some(oauth.borrow().to_owned());
self
}

/// Set the OIDC configuration for this edge.
///
/// https://ngrok.com/docs/http/openid-connect/
pub fn oidc(&mut self, oidc: impl Borrow<OidcOptions>) -> &mut Self {
self.options.oidc = Some(oidc.borrow().to_owned());
self
}

/// Configures webhook verification for this edge.
///
/// https://ngrok.com/docs/http/webhook-verification/
pub fn webhook_verification(
&mut self,
provider: impl Into<String>,
Expand All @@ -357,11 +393,15 @@ impl HttpTunnelBuilder {
}

/// Add the provided regex to the allowlist.
///
/// https://ngrok.com/docs/http/user-agent-filter/
pub fn allow_user_agent(&mut self, regex: impl Into<String>) -> &mut Self {
self.options.user_agent_filter.allow(regex);
self
}
/// Add the provided regex to the denylist.
///
/// https://ngrok.com/docs/http/user-agent-filter/
pub fn deny_user_agent(&mut self, regex: impl Into<String>) -> &mut Self {
self.options.user_agent_filter.deny(regex);
self
Expand Down
6 changes: 6 additions & 0 deletions ngrok/src/config/labeled.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,12 +62,16 @@ impl_builder! {
impl LabeledTunnelBuilder {
/// Sets the opaque metadata string for this tunnel.
/// Viewable via the API.
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn metadata(&mut self, metadata: impl Into<String>) -> &mut Self {
self.options.common_opts.metadata = Some(metadata.into());
self
}

/// Add a label, value pair for this tunnel.
///
/// https://ngrok.com/docs/network-edge/edges/#tunnel-group
pub fn label(&mut self, label: impl Into<String>, value: impl Into<String>) -> &mut Self {
self.options.labels.insert(label.into(), value.into());
self
Expand All @@ -79,6 +83,8 @@ impl LabeledTunnelBuilder {
/// This overrides the default process info if using
/// [TunnelBuilder::listen], and is in turn overridden by the url provided
/// to [ForwarderBuilder::listen_and_forward].
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn forwards_to(&mut self, forwards_to: impl Into<String>) -> &mut Self {
self.options.common_opts.forwards_to = forwards_to.into().into();
self
Expand Down
2 changes: 2 additions & 0 deletions ngrok/src/config/oauth.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ use crate::internals::proto::{
};

/// Oauth Options configuration
///
/// https://ngrok.com/docs/http/oauth/
#[derive(Clone, Default)]
pub struct OauthOptions {
/// The OAuth provider to use
Expand Down
2 changes: 2 additions & 0 deletions ngrok/src/config/oidc.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ use crate::internals::proto::{
};

/// Oidc Options configuration
///
/// https://ngrok.com/docs/http/openid-connect/
#[derive(Clone, Default)]
pub struct OidcOptions {
issuer_url: String,
Expand Down
12 changes: 12 additions & 0 deletions ngrok/src/config/tcp.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,17 +68,23 @@ impl TunnelConfig for TcpOptions {

impl_builder! {
/// A builder for a tunnel backing a TCP endpoint.
///
/// https://ngrok.com/docs/tcp/
TcpTunnelBuilder, TcpOptions, TcpTunnel, endpoint
}

/// The options for a TCP edge.
impl TcpTunnelBuilder {
/// Add the provided CIDR to the allowlist.
///
/// https://ngrok.com/docs/tcp/ip-restrictions/
pub fn allow_cidr(&mut self, cidr: impl Into<String>) -> &mut Self {
self.options.common_opts.cidr_restrictions.allow(cidr);
self
}
/// Add the provided CIDR to the denylist.
///
/// https://ngrok.com/docs/tcp/ip-restrictions/
pub fn deny_cidr(&mut self, cidr: impl Into<String>) -> &mut Self {
self.options.common_opts.cidr_restrictions.deny(cidr);
self
Expand All @@ -89,6 +95,8 @@ impl TcpTunnelBuilder {
self
}
/// Sets the opaque metadata string for this tunnel.
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn metadata(&mut self, metadata: impl Into<String>) -> &mut Self {
self.options.common_opts.metadata = Some(metadata.into());
self
Expand All @@ -99,11 +107,15 @@ impl TcpTunnelBuilder {
/// This overrides the default process info if using
/// [TunnelBuilder::listen], and is in turn overridden by the url provided
/// to [ForwarderBuilder::listen_and_forward].
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn forwards_to(&mut self, forwards_to: impl Into<String>) -> &mut Self {
self.options.common_opts.forwards_to = Some(forwards_to.into());
self
}
/// Sets the TCP address to request for this edge.
///
/// https://ngrok.com/docs/network-edge/domains-and-tcp-addresses/#tcp-addresses
pub fn remote_addr(&mut self, remote_addr: impl Into<String>) -> &mut Self {
self.options.remote_addr = Some(remote_addr.into());
self
Expand Down
16 changes: 16 additions & 0 deletions ngrok/src/config/tls.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,16 +91,22 @@ impl TunnelConfig for TlsOptions {

impl_builder! {
/// A builder for a tunnel backing a TCP endpoint.
///
/// https://ngrok.com/docs/tls/
TlsTunnelBuilder, TlsOptions, TlsTunnel, endpoint
}

impl TlsTunnelBuilder {
/// Add the provided CIDR to the allowlist.
///
/// https://ngrok.com/docs/tls/ip-restrictions/
pub fn allow_cidr(&mut self, cidr: impl Into<String>) -> &mut Self {
self.options.common_opts.cidr_restrictions.allow(cidr);
self
}
/// Add the provided CIDR to the denylist.
///
/// https://ngrok.com/docs/tls/ip-restrictions/
pub fn deny_cidr(&mut self, cidr: impl Into<String>) -> &mut Self {
self.options.common_opts.cidr_restrictions.deny(cidr);
self
Expand All @@ -111,6 +117,8 @@ impl TlsTunnelBuilder {
self
}
/// Sets the opaque metadata string for this tunnel.
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn metadata(&mut self, metadata: impl Into<String>) -> &mut Self {
self.options.common_opts.metadata = Some(metadata.into());
self
Expand All @@ -121,11 +129,15 @@ impl TlsTunnelBuilder {
/// This overrides the default process info if using
/// [TunnelBuilder::listen], and is in turn overridden by the url provided
/// to [ForwarderBuilder::listen_and_forward].
///
/// https://ngrok.com/docs/api/resources/tunnels/#tunnel-fields
pub fn forwards_to(&mut self, forwards_to: impl Into<String>) -> &mut Self {
self.options.common_opts.forwards_to = Some(forwards_to.into());
self
}
/// Sets the domain to request for this edge.
///
/// https://ngrok.com/docs/network-edge/domains-and-tcp-addresses/#domains
pub fn domain(&mut self, domain: impl Into<String>) -> &mut Self {
self.options.domain = Some(domain.into());
self
Expand All @@ -135,13 +147,17 @@ impl TlsTunnelBuilder {
///
/// These will be used to authenticate client certificates for requests at
/// the ngrok edge.
///
/// https://ngrok.com/docs/tls/mutual-tls/
pub fn mutual_tlsca(&mut self, mutual_tlsca: Bytes) -> &mut Self {
self.options.mutual_tlsca.push(mutual_tlsca);
self
}

/// Sets the key and certificate in PEM format for TLS termination at the
/// ngrok edge.
///
/// https://ngrok.com/docs/tls/tls-termination/
pub fn termination(&mut self, cert_pem: Bytes, key_pem: Bytes) -> &mut Self {
self.options.key_pem = Some(key_pem);
self.options.cert_pem = Some(cert_pem);
Expand Down
8 changes: 8 additions & 0 deletions ngrok/src/session.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -822,21 +822,29 @@ impl Session {
}

/// Start building a tunnel for an HTTP endpoint.
///
/// https://ngrok.com/docs/http/
pub fn http_endpoint(&self) -> HttpTunnelBuilder {
self.clone().into()
}

/// Start building a tunnel for a TCP endpoint.
///
/// https://ngrok.com/docs/tcp/
pub fn tcp_endpoint(&self) -> TcpTunnelBuilder {
self.clone().into()
}

/// Start building a tunnel for a TLS endpoint.
///
/// https://ngrok.com/docs/tls/
pub fn tls_endpoint(&self) -> TlsTunnelBuilder {
self.clone().into()
}

/// Start building a labeled tunnel.
///
/// https://ngrok.com/docs/network-edge/edges/#tunnel-group
pub fn labeled_tunnel(&self) -> LabeledTunnelBuilder {
self.clone().into()
}
Expand Down

0 comments on commit cae525a

Please sign in to comment.