Skip to content

Commit 6feb5a0

Browse files
lucasfernoglucasfernog
committed
refactor(core): api feature flags, documentation (#26)
1 parent 85df94f commit 6feb5a0

8 files changed

Lines changed: 159 additions & 33 deletions

File tree

‎.changes/api-features.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"tauri": patch
3+
---
4+
5+
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‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ fn default_language() -> String {
124124
#[cfg_attr(feature = "schema", derive(JsonSchema))]
125125
#[serde(rename_all = "camelCase", deny_unknown_fields)]
126126
pub struct WixConfig {
127-
/// The installer language. See https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables.
127+
/// The installer language. See <https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables>.
128128
#[serde(default = "default_language")]
129129
pub language: String,
130130
/// A custom .wxs template to use.
@@ -550,12 +550,12 @@ pub struct SecurityConfig {
550550
/// If [`dev_csp`](SecurityConfig.dev_csp) is not specified, this value is also injected on dev.
551551
///
552552
/// This is a really important part of the configuration since it helps you ensure your WebView is secured.
553-
/// See https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP.
553+
/// See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
554554
pub csp: Option<String>,
555555
/// The Content Security Policy that will be injected on all HTML files on development.
556556
///
557557
/// This is a really important part of the configuration since it helps you ensure your WebView is secured.
558-
/// See https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP.
558+
/// See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
559559
pub dev_csp: Option<String>,
560560
}
561561

@@ -848,7 +848,7 @@ pub struct ShellAllowlistConfig {
848848
pub execute: bool,
849849
/// Enable sidecar execution, allowing the JavaScript layer to spawn a sidecar program,
850850
/// an executable that is shipped with the application.
851-
/// For more information see https://tauri.studio/en/docs/usage/guides/bundler/sidecar.
851+
/// For more information see <https://tauri.studio/en/docs/usage/guides/bundler/sidecar>.
852852
#[serde(default)]
853853
pub sidecar: bool,
854854
/// Open URL with the user's default application.

‎core/tauri/Cargo.toml‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -64,11 +64,11 @@ clap = { version = "=3.0.4", optional = true }
6464
notify-rust = { version = "4.5", optional = true }
6565
reqwest = { version = "0.11", features = [ "json", "multipart" ], optional = true }
6666
bytes = { version = "1", features = [ "serde" ], optional = true }
67-
attohttpc = { version = "0.18", features = [ "json", "form" ] }
67+
attohttpc = { version = "0.18", features = [ "json", "form" ], optional = true }
6868
open = { version = "2.0", optional = true }
6969
shared_child = { version = "1.0", optional = true }
7070
os_pipe = { version = "1.0", optional = true }
71-
rfd = { version = "0.6.3", features = [ "parent" ] }
71+
rfd = { version = "0.6.3", features = [ "parent" ], optional = true }
7272
raw-window-handle = "0.4.2"
7373
minisign-verify = { version = "0.2", optional = true }
7474
os_info = { version = "3.0.9", optional = true }
@@ -102,10 +102,18 @@ tokio = { version = "1.15", features = [ "full" ] }
102102
[features]
103103
default = [ "wry", "compression" ]
104104
compression = [ "tauri-macros/compression", "tauri-utils/compression" ]
105-
dox = [ "tauri-runtime-wry/dox" ]
106-
wry = [ "tauri-runtime-wry" ]
107-
cli = [ "clap" ]
108-
custom-protocol = [ "tauri-macros/custom-protocol" ]
105+
wry = ["tauri-runtime-wry"]
106+
custom-protocol = ["tauri-macros/custom-protocol"]
107+
updater = ["minisign-verify", "base64", "dialog-ask"]
108+
http-api = ["attohttpc"]
109+
reqwest-client = ["reqwest", "bytes"]
110+
command = ["shared_child", "os_pipe"]
111+
dialog = ["rfd"]
112+
notification = ["notify-rust"]
113+
cli = ["clap"]
114+
system-tray = ["tauri-runtime/system-tray", "tauri-runtime-wry/system-tray"]
115+
dox = ["tauri-runtime-wry/dox"]
116+
macos-private-api = ["tauri-runtime/macos-private-api", "tauri-runtime-wry/macos-private-api"]
109117
api-all = [
110118
"clipboard-all",
111119
"dialog-all",
@@ -120,16 +128,15 @@ api-all = [
120128
"shell-all",
121129
"window-all"
122130
]
123-
macos-private-api = ["tauri-runtime/macos-private-api", "tauri-runtime-wry/macos-private-api"]
124131
clipboard-all = ["clipboard-write-text", "clipboard-read-text"]
125132
clipboard-read-text = []
126133
clipboard-write-text = []
127134
dialog-all = ["dialog-open", "dialog-save", "dialog-message", "dialog-ask"]
128-
dialog-ask = []
129-
dialog-confirm = []
130-
dialog-message = []
131-
dialog-open = []
132-
dialog-save = []
135+
dialog-ask = ["dialog"]
136+
dialog-confirm = ["dialog"]
137+
dialog-message = ["dialog"]
138+
dialog-open = ["dialog"]
139+
dialog-save = ["dialog"]
133140
fs-all = [
134141
"fs-copy-file",
135142
"fs-create-dir",
@@ -154,23 +161,19 @@ fs-write-binary-file = ["base64"]
154161
fs-write-file = []
155162
global-shortcut-all = []
156163
http-all = ["http-request"]
157-
http-request = []
158-
notification-all = ["notify-rust", "dialog-ask"]
164+
http-request = ["http-api"]
165+
notification-all = ["notification", "dialog-ask"]
159166
os-all = ["os_info"]
160167
path-all = []
161168
process-all = ["process-relaunch", "process-exit"]
162169
process-exit = []
163170
process-relaunch = []
164171
protocol-all = ["protocol-asset"]
165172
protocol-asset = []
166-
reqwest-client = ["reqwest", "bytes"]
167-
command = ["shared_child", "os_pipe"]
168173
shell-all = ["shell-execute", "shell-sidecar", "shell-open"]
169174
shell-execute = ["command"]
170175
shell-sidecar = ["command"]
171176
shell-open = ["open"]
172-
system-tray = ["tauri-runtime/system-tray", "tauri-runtime-wry/system-tray"]
173-
updater = ["minisign-verify", "base64", "dialog-ask"]
174177
window-all = [
175178
"window-create",
176179
"window-center",

‎core/tauri/src/api/error.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ pub enum Error {
2525
#[error("user cancelled the dialog")]
2626
DialogCancelled,
2727
/// The network error.
28-
#[cfg(not(feature = "reqwest-client"))]
28+
#[cfg(all(feature = "http", not(feature = "reqwest-client")))]
2929
#[error("Network Error: {0}")]
3030
Network(#[from] attohttpc::Error),
3131
/// The network error.

‎core/tauri/src/api/mod.rs‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@
33
// SPDX-License-Identifier: MIT
44

55
//! The Tauri API interface.
6-
#![warn(missing_docs)]
7-
// #![feature(const_int_pow)]
86
7+
#[cfg(feature = "dialog")]
8+
#[cfg_attr(doc_cfg, doc(cfg(feature = "dialog")))]
99
pub mod dialog;
1010
pub mod dir;
1111
pub mod file;
12+
#[cfg(feature = "http-api")]
13+
#[cfg_attr(doc_cfg, doc(cfg(feature = "http-api")))]
1214
pub mod http;
1315
pub mod ipc;
1416
pub mod path;
@@ -25,7 +27,8 @@ pub mod cli;
2527
#[cfg_attr(doc_cfg, doc(cfg(feature = "cli")))]
2628
pub use clap;
2729

28-
#[cfg(notification_all)]
30+
#[cfg(feature = "notification")]
31+
#[cfg_attr(doc_cfg, doc(cfg(feature = "notification")))]
2932
pub mod notification;
3033

3134
mod error;

‎core/tauri/src/api/shell.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
77
use std::str::FromStr;
88

9-
/// Program to use on the [`open`] call.
9+
/// Program to use on the [`open()`] call.
1010
pub enum Program {
1111
/// Use the `open` program.
1212
Open,

‎core/tauri/src/endpoints/http.rs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
// SPDX-License-Identifier: MIT
44

55
use super::InvokeContext;
6-
use crate::api::http::{ClientBuilder, HttpRequestBuilder, ResponseData};
76
use crate::Runtime;
87
use serde::Deserialize;
98
use tauri_macros::{module_command_handler, CommandModule};
@@ -14,6 +13,15 @@ use std::{
1413
sync::{Arc, Mutex},
1514
};
1615

16+
#[cfg(http_request)]
17+
use crate::api::http::{ClientBuilder, HttpRequestBuilder, ResponseData};
18+
#[cfg(not(http_request))]
19+
type ClientBuilder = ();
20+
#[cfg(not(http_request))]
21+
type HttpRequestBuilder = ();
22+
#[cfg(not(http_request))]
23+
type ResponseData = ();
24+
1725
type ClientId = u32;
1826
#[cfg(http_request)]
1927
type ClientStore = Arc<Mutex<HashMap<ClientId, crate::api::http::Client>>>;

‎core/tauri/src/lib.rs‎

Lines changed: 112 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,123 @@
88
//!
99
//! # Cargo features
1010
//!
11-
//! The following are a list of Cargo features that can be enabled or disabled:
11+
//! 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:
1212
//!
1313
//! - **wry** *(enabled by default)*: Enables the [wry](https://github.com/tauri-apps/wry) runtime. Only disable it if you want a custom runtime.
14+
//! - **custom-protocol**: Feature managed by the Tauri CLI. When enabled, Tauri assumes a production environment instead of a development one.
15+
//! - **updater**: Enables the application auto updater. Enabled by default if the `updater` config is defined on the `tauri.conf.json` file.
16+
//! - **http-api**: Enables the [`api::http`] module.
1417
//! - **reqwest-client**: Uses `reqwest` as HTTP client on the `http` APIs. Improves performance, but increases the bundle size.
18+
//! - **command**: Enables the [`api::process::Command`] APIs.
19+
//! - **dialog**: Enables the [`api::dialog`] module.
20+
//! - **notification**: Enables the [`api::notification`] module.
1521
//! - **cli**: Enables usage of `clap` for CLI argument parsing. Enabled by default if the `cli` config is defined on the `tauri.conf.json` file.
1622
//! - **system-tray**: Enables application system tray API. Enabled by default if the `systemTray` config is defined on the `tauri.conf.json` file.
1723
//! - **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.
18-
//! - **updater**: Enables the application auto updater. Enabled by default if the `updater` config is defined on the `tauri.conf.json` file.
19-
//! - **egui**: Enables method to create a native egui window. This can be used for creating native
20-
//! OpenGL contexts or [egui](https://github.com/emilk/egui) widgets.
24+
//! - **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.
25+
//!
26+
//! ## Cargo allowlist features
27+
//!
28+
//! 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.
29+
//! These features are automatically enabled by the Tauri CLI based on the `allowlist` configuration under `tauri.conf.json`.
30+
//!
31+
//! - **api-all**: Enables all API endpoints.
32+
//!
33+
//! ### Clipboard allowlist
34+
//!
35+
//! - **clipboard-all**: Enables all [Clipboard APIs](https://tauri.studio/en/docs/api/js/modules/clipboard/).
36+
//! - **clipboard-read-text**: Enables the [`readText` API](https://tauri.studio/en/docs/api/js/modules/clipboard/#readtext).
37+
//! - **clipboard-write-text**: Enables the [`writeText` API](https://tauri.studio/en/docs/api/js/modules/clipboard/#writetext).
38+
//!
39+
//! ### Dialog allowlist
40+
//!
41+
//! - **dialog-all**: Enables all [Dialog APIs](https://tauri.studio/en/docs/api/js/modules/dialog).
42+
//! - **dialog-ask**: Enables the [`ask` API](https://tauri.studio/en/docs/api/js/modules/dialog#ask).
43+
//! - **dialog-confirm**: Enables the [`confirm` API](https://tauri.studio/en/docs/api/js/modules/dialog#confirm).
44+
//! - **dialog-message**: Enables the [`message` API](https://tauri.studio/en/docs/api/js/modules/dialog#message).
45+
//! - **dialog-open**: Enables the [`open` API](https://tauri.studio/en/docs/api/js/modules/dialog#open).
46+
//! - **dialog-save**: Enables the [`save` API](https://tauri.studio/en/docs/api/js/modules/dialog#save).
47+
//!
48+
//! ### Filesystem allowlist
49+
//!
50+
//! - **fs-all**: Enables all [Filesystem APIs](https://tauri.studio/en/docs/api/js/modules/fs).
51+
//! - **fs-copy-file**: Enables the [`copyFile` API](https://tauri.studio/en/docs/api/js/modules/fs#copyfile).
52+
//! - **fs-create-dir**: Enables the [`createDir` API](https://tauri.studio/en/docs/api/js/modules/fs#createdir).
53+
//! - **fs-read-binary-file**: Enables the [`readBinaryFile` API](https://tauri.studio/en/docs/api/js/modules/fs#readbinaryfile).
54+
//! - **fs-read-dir**: Enables the [`readDir` API](https://tauri.studio/en/docs/api/js/modules/fs#readdir).
55+
//! - **fs-read-text-file**: Enables the [`readTextFile` API](https://tauri.studio/en/docs/api/js/modules/fs#readtextfile).
56+
//! - **fs-remove-dir**: Enables the [`removeDir` API](https://tauri.studio/en/docs/api/js/modules/fs#removedir).
57+
//! - **fs-remove-file**: Enables the [`removeFile` API](https://tauri.studio/en/docs/api/js/modules/fs#removefile).
58+
//! - **fs-rename-file**: Enables the [`renameFile` API](https://tauri.studio/en/docs/api/js/modules/fs#renamefile).
59+
//! - **fs-write-binary-file**: Enables the [`writeBinaryFile` API](https://tauri.studio/en/docs/api/js/modules/fs#writebinaryfile).
60+
//! - **fs-write-file**: Enables the [`writeFile` API](https://tauri.studio/en/docs/api/js/modules/fs#writefile).
61+
//!
62+
//! ### Global shortcut allowlist
63+
//!
64+
//! - **global-shortcut-all**: Enables all [GlobalShortcut APIs](https://tauri.studio/en/docs/api/js/modules/globalShortcut).
65+
//!
66+
//! ### HTTP allowlist
67+
//!
68+
//! - **http-all**: Enables all [HTTP APIs](https://tauri.studio/en/docs/api/js/modules/http).
69+
//! - **http-request**: Enables the [`request` APIs](https://tauri.studio/en/docs/api/js/classes/http.client/).
70+
//!
71+
//! ### Notification allowlist
72+
//!
73+
//! - **notification-all**: Enables all [Notification APIs](https://tauri.studio/en/docs/api/js/modules/notification).
74+
//!
75+
//! ### OS allowlist
76+
//!
77+
//! - **os-all**: Enables all [OS APIs](https://tauri.studio/en/docs/api/js/modules/os).
78+
//!
79+
//! ### Path allowlist
80+
//!
81+
//! - **path-all**: Enables all [Path APIs](https://tauri.studio/en/docs/api/js/modules/path).
82+
//!
83+
//! ### Process allowlist
84+
//!
85+
//! - **process-all**: Enables all [Process APIs](https://tauri.studio/en/docs/api/js/modules/process).
86+
//! - **process-exit**: Enables the [`exit` API](https://tauri.studio/en/docs/api/js/modules/process#exit).
87+
//! - **process-relaunch**: Enables the [`relaunch` API](https://tauri.studio/en/docs/api/js/modules/process#relaunch).
88+
//!
89+
//! ### Protocol allowlist
90+
//!
91+
//! - **protocol-all**: Enables all Protocol APIs.
92+
//! - **protocol-asset**: Enables the `asset` custom protocol.
93+
//!
94+
//! ### Shell allowlist
95+
//!
96+
//! - **shell-all**: Enables all [Clipboard APIs](https://tauri.studio/en/docs/api/js/modules/shell).
97+
//! - **shell-execute**: Enables [executing arbitrary programs](https://tauri.studio/en/docs/api/js/classes/shell.Command#constructor).
98+
//! - **shell-sidecar**: Enables [executing a `sidecar` program](https://tauri.studio/en/docs/api/js/classes/shell.Command#sidecar).
99+
//! - **shell-open**: Enables the [`open` API](https://tauri.studio/en/docs/api/js/modules/shell#open).
100+
//!
101+
//! ### Window allowlist
102+
//!
103+
//! - **window-all**: Enables all [Window APIs](https://tauri.studio/en/docs/api/js/modules/window).
104+
//! - **window-create**: Enables the API used to [create new windows](https://tauri.studio/en/docs/api/js/classes/window.webviewwindow/).
105+
//! - **window-center**: Enables the [`center` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#center).
106+
//! - **window-request-user-attention**: Enables the [`requestUserAttention` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#requestuserattention).
107+
//! - **window-set-resizable**: Enables the [`setResizable` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setresizable).
108+
//! - **window-set-title**: Enables the [`setTitle` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#settitle).
109+
//! - **window-maximize**: Enables the [`maximize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#maximize).
110+
//! - **window-unmaximize**: Enables the [`unmaximize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#unmaximize).
111+
//! - **window-minimize**: Enables the [`minimize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#minimize).
112+
//! - **window-unminimize**: Enables the [`unminimize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#unminimize).
113+
//! - **window-show**: Enables the [`show` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#show).
114+
//! - **window-hide**: Enables the [`hide` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#hide).
115+
//! - **window-close**: Enables the [`close` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#close).
116+
//! - **window-set-decorations**: Enables the [`setDecorations` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setdecorations).
117+
//! - **window-set-always-on-top**: Enables the [`setAlwaysOnTop` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setalwaysontop).
118+
//! - **window-set-size**: Enables the [`setSize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setsize).
119+
//! - **window-set-min-size**: Enables the [`setMinSize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setminsize).
120+
//! - **window-set-max-size**: Enables the [`setMaxSize` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setmaxsize).
121+
//! - **window-set-position**: Enables the [`setPosition` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setposition).
122+
//! - **window-set-fullscreen**: Enables the [`setFullscreen` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setfullscreen).
123+
//! - **window-set-focus**: Enables the [`setFocus` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setfocus).
124+
//! - **window-set-icon**: Enables the [`setIcon` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#seticon).
125+
//! - **window-set-skip-taskbar**: Enables the [`setSkipTaskbar` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#setskiptaskbar).
126+
//! - **window-start-dragging**: Enables the [`startDragging` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#startdragging).
127+
//! - **window-print**: Enables the [`print` API](https://tauri.studio/en/docs/api/js/classes/window.WebviewWindow#print).
21128
22129
#![warn(missing_docs, rust_2018_idioms)]
23130
#![cfg_attr(doc_cfg, feature(doc_cfg))]
@@ -153,7 +260,7 @@ macro_rules! tauri_build_context {
153260
/// User supplied data required inside of a Tauri application.
154261
///
155262
/// # Stability
156-
/// This is the output of the `tauri::generate_context!` macro, and is not considered part of the stable API.
263+
/// This is the output of the [`generate_context`] macro, and is not considered part of the stable API.
157264
/// Unless you know what you are doing and are prepared for this type to have breaking changes, do not create it yourself.
158265
pub struct Context<A: Assets> {
159266
pub(crate) config: Config,

0 commit comments

Comments
 (0)