mz_adapter_types/
dyncfgs.rs

1// Copyright Materialize, Inc. and contributors. All rights reserved.
2//
3// Use of this software is governed by the Business Source License
4// included in the LICENSE file.
5//
6// As of the Change Date specified in that file, in accordance with
7// the Business Source License, use of this software will be governed
8// by the Apache License, Version 2.0.
9
10//! Dyncfgs used by the adapter layer.
11
12use std::time::Duration;
13
14use mz_dyncfg::{Config, ConfigSet};
15
16pub const ALLOW_USER_SESSIONS: Config<bool> = Config::new(
17    "allow_user_sessions",
18    true,
19    "Whether to allow user roles to create new sessions. When false, only system roles will be permitted to create new sessions.",
20);
21
22// Slightly awkward with the WITH prefix, but we can't start with a 0..
23pub const WITH_0DT_DEPLOYMENT_MAX_WAIT: Config<Duration> = Config::new(
24    "with_0dt_deployment_max_wait",
25    // One year, which in practice makes it so we never cut over when not
26    // hydrated. To prevent cutting over unilaterally when there is an issue.
27    Duration::from_hours(365 * 24),
28    "How long to wait at most for clusters to be hydrated, when doing a zero-downtime deployment.",
29);
30
31pub const WITH_0DT_DEPLOYMENT_DDL_CHECK_INTERVAL: Config<Duration> = Config::new(
32    "with_0dt_deployment_ddl_check_interval",
33    Duration::from_secs(5 * 60),
34    "How often to check for DDL changes during zero-downtime deployment.",
35);
36
37pub const ENABLE_0DT_DEPLOYMENT_PANIC_AFTER_TIMEOUT: Config<bool> = Config::new(
38    "enable_0dt_deployment_panic_after_timeout",
39    false,
40    "Whether to panic if the maximum wait time is reached but preflight checks have not succeeded.",
41);
42
43pub const WITH_0DT_DEPLOYMENT_CAUGHT_UP_CHECK_INTERVAL: Config<Duration> = Config::new(
44    // The feature flag name is historical.
45    "0dt_deployment_hydration_check_interval",
46    Duration::from_secs(10),
47    "Interval at which to check whether clusters are caught up, when doing zero-downtime deployment.",
48);
49
50pub const WITH_0DT_CAUGHT_UP_CHECK_ALLOWED_LAG: Config<Duration> = Config::new(
51    "with_0dt_caught_up_check_allowed_lag",
52    Duration::from_secs(60),
53    "Maximum allowed lag when determining whether collections are caught up for 0dt deployments.",
54);
55
56pub const WITH_0DT_CAUGHT_UP_CHECK_CUTOFF: Config<Duration> = Config::new(
57    "with_0dt_caught_up_check_cutoff",
58    Duration::from_secs(2 * 60 * 60), // 2 hours
59    "Collections whose write frontier is behind 'now' by more than the cutoff are ignored when doing caught-up checks for 0dt deployments.",
60);
61
62pub const ENABLE_0DT_CAUGHT_UP_REPLICA_STATUS_CHECK: Config<bool> = Config::new(
63    "enable_0dt_caught_up_replica_status_check",
64    true,
65    "Enable checking for crash/OOM-looping replicas during 0dt caught-up checks. Emergency break-glass flag to disable this feature if needed.",
66);
67
68/// Enable logging of statement lifecycle events in mz_internal.mz_statement_lifecycle_history.
69pub const ENABLE_STATEMENT_LIFECYCLE_LOGGING: Config<bool> = Config::new(
70    "enable_statement_lifecycle_logging",
71    true,
72    "Enable logging of statement lifecycle events in mz_internal.mz_statement_lifecycle_history.",
73);
74
75/// Enable installation of introspection subscribes.
76pub const ENABLE_INTROSPECTION_SUBSCRIBES: Config<bool> = Config::new(
77    "enable_introspection_subscribes",
78    true,
79    "Enable installation of introspection subscribes.",
80);
81
82/// Enable sending subscribes down the new frontend-peek path.
83pub const ENABLE_FRONTEND_SUBSCRIBES: Config<bool> = Config::new(
84    "enable_frontend_subscribes",
85    true,
86    "Enable sending subscribes down the new frontend-peek path.",
87);
88
89/// The plan insights notice will not investigate fast path clusters if plan optimization took longer than this.
90pub const PLAN_INSIGHTS_NOTICE_FAST_PATH_CLUSTERS_OPTIMIZE_DURATION: Config<Duration> = Config::new(
91    "plan_insights_notice_fast_path_clusters_optimize_duration",
92    // Looking at production values of the mz_optimizer_e2e_optimization_time_seconds metric, most
93    // optimizations run faster than 10ms, so this should still work well for most queries. We want
94    // to avoid the case where an optimization took just under this value and there are lots of
95    // clusters, so the extra delay to produce the plan insights notice will take the optimization
96    // time * the number of clusters longer.
97    Duration::from_millis(10),
98    "Enable plan insights fast path clusters calculation if the optimize step took less than this duration.",
99);
100
101/// Whether to use an expression cache on boot.
102pub const ENABLE_EXPRESSION_CACHE: Config<bool> = Config::new(
103    "enable_expression_cache",
104    true,
105    "Use a cache to store optimized expressions to help speed up start times.",
106);
107
108/// Whether to enable password authentication.
109pub const ENABLE_PASSWORD_AUTH: Config<bool> = Config::new(
110    "enable_password_auth",
111    false,
112    "Enable password authentication.",
113);
114
115/// OIDC issuer URL.
116pub const OIDC_ISSUER: Config<Option<&'static str>> =
117    Config::new("oidc_issuer", None, "OIDC issuer URL.");
118
119/// OIDC audience (client IDs). When empty, audience validation is skipped.
120/// Validates that the JWT's `aud` claim contains at least one of these values.
121/// It is insecure to skip validation because it is the only
122/// mechanism preventing attackers from authenticating using a JWT
123/// issued by a dummy application, but from the same identity provider.
124pub const OIDC_AUDIENCE: Config<fn() -> serde_json::Value> = Config::new(
125    "oidc_audience",
126    || serde_json::json!([]),
127    "OIDC audience (client IDs). A JSON array of strings. When empty, audience validation is skipped.",
128);
129
130/// OIDC authentication claim to use as username
131pub const OIDC_AUTHENTICATION_CLAIM: Config<&'static str> = Config::new(
132    "oidc_authentication_claim",
133    "sub",
134    "OIDC authentication claim to use as username.",
135);
136
137/// Whether OIDC group-to-role sync is enabled.
138/// When true, JWT group claims are used to sync role memberships on login.
139pub const OIDC_GROUP_ROLE_SYNC_ENABLED: Config<bool> = Config::new(
140    "oidc_group_role_sync_enabled",
141    false,
142    "Enable OIDC JWT group-to-role membership sync on login.",
143);
144
145/// The JWT claim path that contains group memberships. May be a bare claim
146/// name (e.g. `groups`) or a dot-separated path into nested objects (e.g.
147/// `customClaims.groups`).
148pub const OIDC_GROUP_CLAIM: Config<&'static str> = Config::new(
149    "oidc_group_claim",
150    "groups",
151    "JWT claim path containing group memberships for role sync. Supports dot-separated paths into nested objects (e.g. customClaims.groups).",
152);
153
154/// Whether to reject login when group sync fails (strict/fail-closed mode).
155/// When false (default), sync failures are logged but login proceeds (fail-open).
156pub const OIDC_GROUP_ROLE_SYNC_STRICT: Config<bool> = Config::new(
157    "oidc_group_role_sync_strict",
158    false,
159    "When true, reject login if OIDC group-to-role sync fails (fail-closed).",
160);
161
162pub const PERSIST_FAST_PATH_ORDER: Config<bool> = Config::new(
163    "persist_fast_path_order",
164    false,
165    "If set, send queries with a compatible literal constraint or ordering clause down the Persist fast path.",
166);
167
168/// Whether to enforce that S3 Tables connections are in the same region as the Materialize
169/// environment.
170pub const ENABLE_S3_TABLES_REGION_CHECK: Config<bool> = Config::new(
171    "enable_s3_tables_region_check",
172    false,
173    "Whether to enforce that S3 Tables connections are in the same region as the environment.",
174);
175
176/// Whether the MCP agent endpoint is enabled.
177pub const ENABLE_MCP_AGENT: Config<bool> = Config::new(
178    "enable_mcp_agent",
179    true,
180    "Whether the MCP agent HTTP endpoint is enabled. When false, requests to /api/mcp/agent return 503 Service Unavailable.",
181);
182
183/// Whether the MCP agent query tool is enabled.
184/// When false, the `query` tool is hidden from tools/list and calls to it return an error.
185/// Agents can still use `get_data_products` and `get_data_product_details`.
186pub const ENABLE_MCP_AGENT_QUERY_TOOL: Config<bool> = Config::new(
187    "enable_mcp_agent_query_tool",
188    true,
189    "Whether the MCP agent query tool is enabled. When false, the query tool is not advertised and calls to it are rejected. Agents can still discover and inspect data products.",
190);
191
192/// Whether the MCP developer endpoint is enabled.
193pub const ENABLE_MCP_DEVELOPER: Config<bool> = Config::new(
194    "enable_mcp_developer",
195    true,
196    "Whether the MCP developer HTTP endpoint is enabled. When false, requests to /api/mcp/developer return 503 Service Unavailable.",
197);
198
199/// Whether the external metrics endpoint on environmentd is enabled.
200pub const ENABLE_PUBLIC_METRICS_ENDPOINT: Config<bool> = Config::new(
201    "enable_public_metrics_endpoint",
202    true,
203    "Whether the external metrics endpoint on environmentd is enabled. When false, requests return 503.",
204);
205
206/// Maximum size (in bytes) of MCP tool response content after JSON serialization.
207/// Responses exceeding this limit are rejected with a clear error telling the
208/// agent to narrow its query. Keeps responses within LLM context window limits.
209pub const MCP_MAX_RESPONSE_SIZE: Config<usize> = Config::new(
210    "mcp_max_response_size",
211    1_000_000,
212    "Maximum size in bytes of MCP tool response content. Responses exceeding this limit are rejected with an error telling the agent to narrow its query.",
213);
214
215/// Number of user IDs to pre-allocate in a batch. Pre-allocating IDs avoids
216/// a persist write + oracle call per DDL statement.
217pub const USER_ID_POOL_BATCH_SIZE: Config<u32> = Config::new(
218    "user_id_pool_batch_size",
219    512,
220    "Number of user IDs to pre-allocate in a batch for DDL operations.",
221);
222
223/// OIDC client ID for the web console.
224pub const CONSOLE_OIDC_CLIENT_ID: Config<&'static str> = Config::new(
225    "console_oidc_client_id",
226    "",
227    "OIDC client ID for the web console.",
228);
229
230/// Space-separated OIDC scopes requested by the web console.
231pub const CONSOLE_OIDC_SCOPES: Config<&'static str> = Config::new(
232    "console_oidc_scopes",
233    "",
234    "Space-separated OIDC scopes requested by the web console.",
235);
236
237/// Interval at which to collect per-object arrangement size snapshots for the history table.
238pub const ARRANGEMENT_SIZE_HISTORY_COLLECTION_INTERVAL: Config<Duration> = Config::new(
239    "arrangement_size_history_collection_interval",
240    Duration::from_hours(1),
241    "Interval at which to collect and snapshot per-object arrangement sizes \
242     into mz_internal.mz_object_arrangement_size_history.",
243);
244
245/// How long to retain per-object arrangement size history.
246pub const ARRANGEMENT_SIZE_HISTORY_RETENTION_PERIOD: Config<Duration> = Config::new(
247    "arrangement_size_history_retention_period",
248    Duration::from_hours(7 * 24),
249    "How long to retain rows in mz_internal.mz_object_arrangement_size_history.",
250);
251
252/// Adds the full set of all adapter `Config`s.
253pub fn all_dyncfgs(configs: ConfigSet) -> ConfigSet {
254    configs
255        .add(&ALLOW_USER_SESSIONS)
256        .add(&WITH_0DT_DEPLOYMENT_MAX_WAIT)
257        .add(&WITH_0DT_DEPLOYMENT_DDL_CHECK_INTERVAL)
258        .add(&ENABLE_0DT_DEPLOYMENT_PANIC_AFTER_TIMEOUT)
259        .add(&WITH_0DT_DEPLOYMENT_CAUGHT_UP_CHECK_INTERVAL)
260        .add(&WITH_0DT_CAUGHT_UP_CHECK_ALLOWED_LAG)
261        .add(&WITH_0DT_CAUGHT_UP_CHECK_CUTOFF)
262        .add(&ENABLE_0DT_CAUGHT_UP_REPLICA_STATUS_CHECK)
263        .add(&ENABLE_STATEMENT_LIFECYCLE_LOGGING)
264        .add(&ENABLE_INTROSPECTION_SUBSCRIBES)
265        .add(&ENABLE_FRONTEND_SUBSCRIBES)
266        .add(&PLAN_INSIGHTS_NOTICE_FAST_PATH_CLUSTERS_OPTIMIZE_DURATION)
267        .add(&ENABLE_EXPRESSION_CACHE)
268        .add(&ENABLE_PASSWORD_AUTH)
269        .add(&OIDC_ISSUER)
270        .add(&OIDC_AUDIENCE)
271        .add(&OIDC_AUTHENTICATION_CLAIM)
272        .add(&OIDC_GROUP_ROLE_SYNC_ENABLED)
273        .add(&OIDC_GROUP_CLAIM)
274        .add(&OIDC_GROUP_ROLE_SYNC_STRICT)
275        .add(&PERSIST_FAST_PATH_ORDER)
276        .add(&ENABLE_S3_TABLES_REGION_CHECK)
277        .add(&ENABLE_MCP_AGENT)
278        .add(&ENABLE_MCP_AGENT_QUERY_TOOL)
279        .add(&ENABLE_MCP_DEVELOPER)
280        .add(&ENABLE_PUBLIC_METRICS_ENDPOINT)
281        .add(&MCP_MAX_RESPONSE_SIZE)
282        .add(&USER_ID_POOL_BATCH_SIZE)
283        .add(&CONSOLE_OIDC_CLIENT_ID)
284        .add(&CONSOLE_OIDC_SCOPES)
285        .add(&ARRANGEMENT_SIZE_HISTORY_COLLECTION_INTERVAL)
286        .add(&ARRANGEMENT_SIZE_HISTORY_RETENTION_PERIOD)
287}
mz_adapter_types/dyncfgs.rs

mz_adapter_types/
dyncfgs.rs
