refactor(core): api feature flags, documentation (#26)

.changes/api-features.md

@@ -0,0 +1,5 @@
+---
+"tauri": patch
+---
+
+The `tauri::api` modules `http`, `notification`, `dialog`, and `process::Command` APIs are now hidden behind a feature flag, `http-api`, `notification`, `dialog` and `command`, respectively.

core/tauri-utils/src/config.rs

@@ -124,7 +124,7 @@ fn default_language() -> String {
 #[cfg_attr(feature = "schema", derive(JsonSchema))]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct WixConfig {
-  /// The installer language. See https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables.
+  /// The installer language. See <https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables>.
   #[serde(default = "default_language")]
   pub language: String,
   /// A custom .wxs template to use.
@@ -550,12 +550,12 @@ pub struct SecurityConfig {
   /// If [`dev_csp`](SecurityConfig.dev_csp) is not specified, this value is also injected on dev.
   ///
   /// This is a really important part of the configuration since it helps you ensure your WebView is secured.
-  /// See https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP.
+  /// See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
   pub csp: Option<String>,
   /// The Content Security Policy that will be injected on all HTML files on development.
   ///
   /// This is a really important part of the configuration since it helps you ensure your WebView is secured.
-  /// See https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP.
+  /// See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
   pub dev_csp: Option<String>,
 }
 
@@ -848,7 +848,7 @@ pub struct ShellAllowlistConfig {
   pub execute: bool,
   /// Enable sidecar execution, allowing the JavaScript layer to spawn a sidecar program,
   /// an executable that is shipped with the application.
-  /// For more information see https://tauri.studio/en/docs/usage/guides/bundler/sidecar.
+  /// For more information see <https://tauri.studio/en/docs/usage/guides/bundler/sidecar>.
   #[serde(default)]
   pub sidecar: bool,
   /// Open URL with the user's default application.

core/tauri/Cargo.toml

@@ -64,11 +64,11 @@ clap = { version = "=3.0.4", optional = true }
 notify-rust = { version = "4.5", optional = true }
 reqwest = { version = "0.11", features = [ "json", "multipart" ], optional = true }
 bytes = { version = "1", features = [ "serde" ], optional = true }
-attohttpc = { version = "0.18", features = [ "json", "form" ] }
+attohttpc = { version = "0.18", features = [ "json", "form" ], optional = true }
 open = { version = "2.0", optional = true }
 shared_child = { version = "1.0", optional = true }
 os_pipe = { version = "1.0", optional = true }
-rfd = { version = "0.6.3", features = [ "parent" ] }
+rfd = { version = "0.6.3", features = [ "parent" ], optional = true }
 raw-window-handle = "0.4.2"
 minisign-verify = { version = "0.2", optional = true }
 os_info = { version = "3.0.9", optional = true }
@@ -102,10 +102,18 @@ tokio = { version = "1.15", features = [ "full" ] }
 [features]
 default = [ "wry", "compression" ]
 compression = [ "tauri-macros/compression", "tauri-utils/compression" ]
-dox = [ "tauri-runtime-wry/dox" ]
-wry = [ "tauri-runtime-wry" ]
-cli = [ "clap" ]
-custom-protocol = [ "tauri-macros/custom-protocol" ]
+wry = ["tauri-runtime-wry"]
+custom-protocol = ["tauri-macros/custom-protocol"]
+updater = ["minisign-verify", "base64", "dialog-ask"]
+http-api = ["attohttpc"]
+reqwest-client = ["reqwest", "bytes"]
+command = ["shared_child", "os_pipe"]
+dialog = ["rfd"]
+notification = ["notify-rust"]
+cli = ["clap"]
+system-tray = ["tauri-runtime/system-tray", "tauri-runtime-wry/system-tray"]
+dox = ["tauri-runtime-wry/dox"]
+macos-private-api = ["tauri-runtime/macos-private-api", "tauri-runtime-wry/macos-private-api"]
 api-all = [
   "clipboard-all",
   "dialog-all",
@@ -120,16 +128,15 @@ api-all = [
   "shell-all",
   "window-all"
 ]
-macos-private-api = ["tauri-runtime/macos-private-api", "tauri-runtime-wry/macos-private-api"]
 clipboard-all = ["clipboard-write-text", "clipboard-read-text"]
 clipboard-read-text = []
 clipboard-write-text = []
 dialog-all = ["dialog-open", "dialog-save", "dialog-message", "dialog-ask"]
-dialog-ask = []
-dialog-confirm = []
-dialog-message = []
-dialog-open = []
-dialog-save = []
+dialog-ask = ["dialog"]
+dialog-confirm = ["dialog"]
+dialog-message = ["dialog"]
+dialog-open = ["dialog"]
+dialog-save = ["dialog"]
 fs-all = [
   "fs-copy-file",
   "fs-create-dir",
@@ -154,8 +161,8 @@ fs-write-binary-file = ["base64"]
 fs-write-file = []
 global-shortcut-all = []
 http-all = ["http-request"]
-http-request = []
-notification-all = ["notify-rust", "dialog-ask"]
+http-request = ["http-api"]
+notification-all = ["notification", "dialog-ask"]
 os-all = ["os_info"]
 path-all = []
 process-all = ["process-relaunch", "process-exit"]
@@ -163,14 +170,10 @@ process-exit = []
 process-relaunch = []
 protocol-all = ["protocol-asset"]
 protocol-asset = []
-reqwest-client = ["reqwest", "bytes"]
-command = ["shared_child", "os_pipe"]
 shell-all = ["shell-execute", "shell-sidecar", "shell-open"]
 shell-execute = ["command"]
 shell-sidecar = ["command"]
 shell-open = ["open"]
-system-tray = ["tauri-runtime/system-tray", "tauri-runtime-wry/system-tray"]
-updater = ["minisign-verify", "base64", "dialog-ask"]
 window-all = [
   "window-create",
   "window-center",

core/tauri/src/api/error.rs

@@ -25,7 +25,7 @@ pub enum Error {
   #[error("user cancelled the dialog")]
   DialogCancelled,
   /// The network error.
-  #[cfg(not(feature = "reqwest-client"))]
+  #[cfg(all(feature = "http", not(feature = "reqwest-client")))]
   #[error("Network Error: {0}")]
   Network(#[from] attohttpc::Error),
   /// The network error.

core/tauri/src/api/mod.rs

@@ -3,12 +3,14 @@
 // SPDX-License-Identifier: MIT
 
 //! The Tauri API interface.
-#![warn(missing_docs)]
-// #![feature(const_int_pow)]
 
+#[cfg(feature = "dialog")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "dialog")))]
 pub mod dialog;
 pub mod dir;
 pub mod file;
+#[cfg(feature = "http-api")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "http-api")))]
 pub mod http;
 pub mod ipc;
 pub mod path;
@@ -25,7 +27,8 @@ pub mod cli;
 #[cfg_attr(doc_cfg, doc(cfg(feature = "cli")))]
 pub use clap;
 
-#[cfg(notification_all)]
+#[cfg(feature = "notification")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "notification")))]
 pub mod notification;
 
 mod error;

core/tauri/src/api/shell.rs

@@ -6,7 +6,7 @@
 
 use std::str::FromStr;
 
-/// Program to use on the [`open`] call.
+/// Program to use on the [`open()`] call.
 pub enum Program {
   /// Use the `open` program.
   Open,

core/tauri/src/endpoints/http.rs

@@ -3,7 +3,6 @@
 // SPDX-License-Identifier: MIT
 
 use super::InvokeContext;
-use crate::api::http::{ClientBuilder, HttpRequestBuilder, ResponseData};
 use crate::Runtime;
 use serde::Deserialize;
 use tauri_macros::{module_command_handler, CommandModule};
@@ -14,6 +13,15 @@ use std::{
   sync::{Arc, Mutex},
 };
 
+#[cfg(http_request)]
+use crate::api::http::{ClientBuilder, HttpRequestBuilder, ResponseData};
+#[cfg(not(http_request))]
+type ClientBuilder = ();
+#[cfg(not(http_request))]
+type HttpRequestBuilder = ();
+#[cfg(not(http_request))]
+type ResponseData = ();
+
 type ClientId = u32;
 #[cfg(http_request)]
 type ClientStore = Arc<Mutex<HashMap<ClientId, crate::api::http::Client>>>;

core/tauri/src/lib.rs

@@ -8,16 +8,123 @@
 //!
 //! # Cargo features
 //!
-//! The following are a list of Cargo features that can be enabled or disabled:
+//! The following are a list of [Cargo features](https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-features-section) that can be enabled or disabled:
 //!
 //! - **wry** *(enabled by default)*: Enables the [wry](https://github.com/tauri-apps/wry) runtime. Only disable it if you want a custom runtime.
+//! - **custom-protocol**: Feature managed by the Tauri CLI. When enabled, Tauri assumes a production environment instead of a development one.
+//! - **updater**: Enables the application auto updater. Enabled by default if the `updater` config is defined on the `tauri.conf.json` file.
+//! - **http-api**: Enables the [`api::http`] module.
 //! - **reqwest-client**: Uses `reqwest` as HTTP client on the `http` APIs. Improves performance, but increases the bundle size.
+//! - **command**: Enables the [`api::process::Command`] APIs.
+//! - **dialog**: Enables the [`api::dialog`] module.
+//! - **notification**: Enables the [`api::notification`] module.
 //! - **cli**: Enables usage of `clap` for CLI argument parsing. Enabled by default if the `cli` config is defined on the `tauri.conf.json` file.
 //! - **system-tray**: Enables application system tray API. Enabled by default if the `systemTray` config is defined on the `tauri.conf.json` file.
 //! - **macos-private-api**: Enables features only available in **macOS**'s private APIs, currently the `transparent` window functionality and the `fullScreenEnabled` preference setting to `true`. Enabled by default if the `tauri > macosPrivateApi` config flag is set to `true` on the `tauri.conf.json` file.
-//! - **updater**: Enables the application auto updater. Enabled by default if the `updater` config is defined on the `tauri.conf.json` file.
-//! - **egui**: Enables method to create a native egui window. This can be used for creating native
-//! OpenGL contexts or [egui](https://github.com/emilk/egui) widgets.
+//! - **egui**: Enables method to create a native egui window. This can be used for creating native OpenGL contexts or [egui](https://github.com/emilk/egui) widgets.
+//!
+//! ## Cargo allowlist features
+//!
+//! The following are a list of [Cargo features](https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-features-section) that enables commands for Tauri's API package.
+//! These features are automatically enabled by the Tauri CLI based on the `allowlist` configuration under `tauri.conf.json`.
+//!
+//! - **api-all**: Enables all API endpoints.
+//!
+//! ### Clipboard allowlist
+//!
+//! - **clipboard-all**: Enables all [Clipboard APIs](https://tauri.studio/en/docs/api/js/modules/clipboard/).
+//! - **clipboard-read-text**: Enables the [`readText` API](https://tauri.studio/en/docs/api/js/modules/clipboard/#readtext).
+//! - **clipboard-write-text**: Enables the [`writeText` API](https://tauri.studio/en/docs/api/js/modules/clipboard/#writetext).
+//!
+//! ### Dialog allowlist
+//!
+//! - **dialog-all**: Enables all [Dialog APIs](https://tauri.studio/en/docs/api/js/modules/dialog).
+//! - **dialog-ask**: Enables the [`ask` API](https://tauri.studio/en/docs/api/js/modules/dialog#ask).
+//! - **dialog-confirm**: Enables the [`confirm` API](https://tauri.studio/en/docs/api/js/modules/dialog#confirm).
+//! - **dialog-message**: Enables the [`message` API](https://tauri.studio/en/docs/api/js/modules/dialog#message).
+//! - **dialog-open**: Enables the [`open` API](https://tauri.studio/en/docs/api/js/modules/dialog#open).
+//! - **dialog-save**: Enables the [`save` API](https://tauri.studio/en/docs/api/js/modules/dialog#save).
+//!
+//! ### Filesystem allowlist
+//!
+//! - **fs-all**: Enables all [Filesystem APIs](https://tauri.studio/en/docs/api/js/modules/fs).
+//! - **fs-copy-file**: Enables the [`copyFile` API](https://tauri.studio/en/docs/api/js/modules/fs#copyfile).
+//! - **fs-create-dir**: Enables the [`createDir` API](https://tauri.studio/en/docs/api/js/modules/fs#createdir).
+//! - **fs-read-binary-file**: Enables the [`readBinaryFile` API](https://tauri.studio/en/docs/api/js/modules/fs#readbinaryfile).
+//! - **fs-read-dir**: Enables the [`readDir` API](https://tauri.studio/en/docs/api/js/modules/fs#readdir).
+//! - **fs-read-text-file**: Enables the [`readTextFile` API](https://tauri.studio/en/docs/api/js/modules/fs#readtextfile).
+//! - **fs-remove-dir**: Enables the [`removeDir` API](https://tauri.studio/en/docs/api/js/modules/fs#removedir).
+//! - **fs-remove-file**: Enables the [`removeFile` API](https://tauri.studio/en/docs/api/js/modules/fs#removefile).
+//! - **fs-rename-file**: Enables the [`renameFile` API](https://tauri.studio/en/docs/api/js/modules/fs#renamefile).
+//! - **fs-write-binary-file**: Enables the [`writeBinaryFile` API](https://tauri.studio/en/docs/api/js/modules/fs#writebinaryfile).
+//! - **fs-write-file**: Enables the [`writeFile` API](https://tauri.studio/en/docs/api/js/modules/fs#writefile).
+//!
+//! ### Global shortcut allowlist
+//!
+//! - **global-shortcut-all**: Enables all [GlobalShortcut APIs](https://tauri.studio/en/docs/api/js/modules/globalShortcut).
+//!
+//! ### HTTP allowlist
+//!
+//! - **http-all**: Enables all [HTTP APIs](https://tauri.studio/en/docs/api/js/modules/http).
+//! - **http-request**: Enables the [`request` APIs](https://tauri.studio/en/docs/api/js/classes/http.client/).
+//!
+//! ### Notification allowlist
+//!
+//! - **notification-all**: Enables all [Notification APIs](https://tauri.studio/en/docs/api/js/modules/notification).
+//!
+//! ### OS allowlist
+//!
+//! - **os-all**: Enables all [OS APIs](https://tauri.studio/en/docs/api/js/modules/os).
+//!
+//! ### Path allowlist
+//!
+//! - **path-all**: Enables all [Path APIs](https://tauri.studio/en/docs/api/js/modules/path).
+//!
+//! ### Process allowlist
+//!
+//! - **process-all**: Enables all [Process APIs](https://tauri.studio/en/docs/api/js/modules/process).
+//! - **process-exit**: Enables the [`exit` API](https://tauri.studio/en/docs/api/js/modules/process#exit).
+//! - **process-relaunch**: Enables the [`relaunch` API](https://tauri.studio/en/docs/api/js/modules/process#relaunch).
+//!
+//! ### Protocol allowlist
+//!
+//! - **protocol-all**: Enables all Protocol APIs.
+//! - **protocol-asset**: Enables the `asset` custom protocol.
+//!
+//! ### Shell allowlist
+//!
+//! - **shell-all**: Enables all [Clipboard APIs](https://tauri.studio/en/docs/api/js/modules/shell).
+//! - **shell-execute**: Enables [executing arbitrary programs](https://tauri.studio/en/docs/api/js/classes/shell.Command#constructor).
+//! - **shell-sidecar**: Enables [executing a `sidecar` program](https://tauri.studio/en/docs/api/js/classes/shell.Command#sidecar).
+//! - **shell-open**: Enables the [`open` API](https://tauri.studio/en/docs/api/js/modules/shell#open).
+//!
+//! ### Window allowlist
+//!
+//! - **window-all**: Enables all [Window APIs](https://tauri.studio/en/docs/api/js/modules/window).
+//! - **window-create**: Enables the API used to [create new windows](https://tauri.studio/en/docs/api/js/classes/window.webviewwindow/).
+//! - **window-center**: Enables the [`center` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#center).
+//! - **window-request-user-attention**: Enables the [`requestUserAttention` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#requestuserattention).
+//! - **window-set-resizable**: Enables the [`setResizable` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setresizable).
+//! - **window-set-title**: Enables the [`setTitle` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#settitle).
+//! - **window-maximize**: Enables the [`maximize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#maximize).
+//! - **window-unmaximize**: Enables the [`unmaximize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#unmaximize).
+//! - **window-minimize**: Enables the [`minimize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#minimize).
+//! - **window-unminimize**: Enables the [`unminimize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#unminimize).
+//! - **window-show**: Enables the [`show` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#show).
+//! - **window-hide**: Enables the [`hide` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#hide).
+//! - **window-close**: Enables the [`close` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#close).
+//! - **window-set-decorations**: Enables the [`setDecorations` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setdecorations).
+//! - **window-set-always-on-top**: Enables the [`setAlwaysOnTop` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setalwaysontop).
+//! - **window-set-size**: Enables the [`setSize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setsize).
+//! - **window-set-min-size**: Enables the [`setMinSize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setminsize).
+//! - **window-set-max-size**: Enables the [`setMaxSize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setmaxsize).
+//! - **window-set-position**: Enables the [`setPosition` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setposition).
+//! - **window-set-fullscreen**: Enables the [`setFullscreen` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setfullscreen).
+//! - **window-set-focus**: Enables the [`setFocus` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setfocus).
+//! - **window-set-icon**: Enables the [`setIcon` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#seticon).
+//! - **window-set-skip-taskbar**: Enables the [`setSkipTaskbar` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setskiptaskbar).
+//! - **window-start-dragging**: Enables the [`startDragging` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#startdragging).
+//! - **window-print**: Enables the [`print` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#print).
 
 #![warn(missing_docs, rust_2018_idioms)]
 #![cfg_attr(doc_cfg, feature(doc_cfg))]
@@ -153,7 +260,7 @@ macro_rules! tauri_build_context {
 /// User supplied data required inside of a Tauri application.
 ///
 /// # Stability
-/// This is the output of the `tauri::generate_context!` macro, and is not considered part of the stable API.
+/// This is the output of the [`generate_context`] macro, and is not considered part of the stable API.
 /// Unless you know what you are doing and are prepared for this type to have breaking changes, do not create it yourself.
 pub struct Context<A: Assets> {
   pub(crate) config: Config,