Safeguard levels: fine-tune the amount of runtime validations

[beicause]

Update Bromeon -- tweaked some things, but huge thanks go to @beicause for initiative and the solid groundwork.

Safeguard levels

godot-rust now supports three tiers that differ in the amount of runtime checks and validations that are performed:

🛡️ Strict (default for dev builds)

Lots of additional, sometimes expensive checks. Detects many bugs during development.

• Gd::bind/bind_mut() provides extensive diagnostics to locate runtime borrow errors.
• Array safe conversion checks (for types like Array<i8>).
• RTTI checks on object access (protect against type mismatch edge cases).
• Geometric invariants (e.g. normalized quaternions).
• Access to engine APIs outside valid scope.

⚖️ Balanced (default for release builds)

Basic validity and invariant checks, reasonably fast. Within this level, you should not be able to encounter undefined behavior (UB) in safe Rust code. Invariant violations may however cause panics and logic errors.

• Object liveness checks.
• Gd::bind/bind_mut() cause panics on borrow errors.

☣️ Disengaged

Most checks disabled, sacrifices safety for raw speed. This renders a large part of the godot-rust API unsafe without polluting the code; you opt in via unsafe impl ExtensionLibrary.

Before using this, measure to ensure you truly need the last bit of performance (balanced should be fast enough for most cases; if not, consider bringing it up). Also test your code thoroughly using the other levels first. Undefined behavior and crashes arising from using this level are your full responsibility. When reporting a bug, make sure you can reproduce it under the balanced level.

• Unchecked object access -> instant UB if an object is dead.
• Gd::bind/bind_mut() are unchecked -> UB if mutable aliasing occurs.

Cargo features

You can downgrade 1 level in each dev (Debug) and release Cargo profiles, with following features:

• safeguards-dev-balanced: for dev, use balanced instead of the default strict level.
• safeguards-release-disengaged: for release, use disengaged instead of the default balanced level.

This PR also adds both features to both minimal and full CI runs. There were a lot of missing classifications in test, as well as a few bugs/UB due to wrong #[cfg].

CI and conditional compilation

Speaking of #[cfg], I simplified the way they can be checked for in code. The safeguards usage can be extended over time, and probably replace quite a few #[cfg(debug_assertions)] conditions.

Outlook

Warning

Safeguards are a recent addition to godot-rust and need calibrating over time. If you are unhappy with how the balanced level performs in basic operations, consider bringing it up for discussion. We'd like to offer the disengaged level for power users who really need it, but it shouldn't be the only choice for decent runtime performance, as it comes with heavy trade-offs.

As of v0.4, the above checks are not fully implemented yet. Neither are they guarantees; categorization and naming may change over time.

---

Original description:

Addresses #1276.

Allow configuring safety level through GDEXT_SAFETY_LEVEL_DEBUG and GDEXT_SAFETY_LEVEL_RELEASE environment variables. Not sure if it can be implemented as ExtensionLibrary function. Also implemented as Cargo features may be annoying.

• level 0: no checks.
• level 1: ensures object is alive.
• level 2: and other checks that prevously debug_assertions (RTTI, backtrace, Array elements validation)
  (Correct me if I missed anything).

[GodotRust]

API docs are being generated and will be shortly available at: https://godot-rust.github.io/docs/gdext/pr-1278

[TitanNano]

What if we call this GDEXT_SAFETY_CHECKS_* and the values something like STRICT, MINIMAL and NONE. I find this clearer as a user.

The cfg attribute could also be called with_safety_level or with_checks.

[Bromeon]

Thanks a lot for the pull request! 👍

Please see my comment #1046 (comment) and subsequent response by @TitanNano, where we detailed quite a bit of the design.

Some feedback:

1. My first impression is that I'd rather not have this configured via environment variables, that's rather brittle and easy to silently get wrong (e.g. someone sets the environment variable for Godot, not for rustc). Instead, it should be a Cargo feature. While features are technically additive, we already do a similar thing with api-4-2 etc.

   • I know it can be slightly annoying since you can't easily enable a feature only in the Release config. But this isn't really easier with env vars.

2. Safety profiles should be named, not magic numbers. It's not obvious whether "0" means "no safety" or "no performance". An option is to use the term checks, but it could also be something else.

   • The individual levels could be called fast-unsafe, balanced and paranoid. (To be discussed)
   • Cargo feature would then be checks-fast-unsafe.
   • Conditional compilation would be #[cfg(checks_at_least = "balanced")]. Let's avoid not if possible.

[Yarwin]

I think including chosen safety profile in preamble would be good idea as well (something along the lines of "Initialize godot-rust (API v4.4.stable.official, runtime v4.4.stable.official) fast-unsafe/balanced/slow-safe mode"?).

gdext/godot-ffi/src/lib.rs

Lines 288 to 293 in 0dde85e

	fn print_preamble(version: GDExtensionGodotVersion) {
	let api_version: &'static str = GdextBuild::godot_static_version_string();
	let runtime_version = read_version_string(&version);
	println!("Initialize godot-rust (API {api_version}, runtime {runtime_version})");
	}

---

There are some validity checks which would be nice to cover, albeit I wouldn't sweat too much about it – we can cover them later 😄.

One such example is the PartialEq for Gd<T>:

gdext/godot-core/src/obj/gd.rs

Lines 1078 to 1087 in aaf3ed5

	impl<T: GodotClass> PartialEq for Gd<T> {
	/// ⚠️ Returns whether two `Gd` pointers point to the same object.
	///
	/// # Panics
	/// When `self` or `other` is dead.
	fn eq(&self, other: &Self) -> bool {
	// Panics when one is dead
	self.instance_id() == other.instance_id()
	}
	}

instance_id() checks for object validity, while it could be self.instance_id_unchecked() == other.instance_id_unchecked() (compare potentially dead objects) in fast profile level (or even balanced (2)? It won't cause UB, but may cause follow-up logic errors and panics 🤔).

(I'll underline – I don't think we should sweat to cover all (or even the aforementioned one) the cases, we should just make an issue for tracking them)

[Bromeon]

Yeah, I'd suggest not to add more specific checks in this PR, to get the basic mechanism working first 🙂

As for defaults, it should be:

• in Debug mode: strict/paranoid/extensive checks (highest level)
• in Release mode: balanced checks (middle level)

While it means the user won't get max performance per default, it's better if they don't risk UB by default.

But if we go for Cargo feature, we need to find a way how they can opt in... I could imagine that in Debug mode, many would still want to keep paranoid or balanced checks, while Release builds should have fast performance. It's unfortunately not that easy to specify Cargo features based on the build profile...

[Bromeon]

Hm, 6 new Cargo features is quite a lot, although I see the dilemma.

What would the alternatives be?

[Bromeon]

@beicause could you for now limit this to 3 features?

The compiler invocation is already different due to --release flag, so it should be acceptable to add a --feature xy flag as well. If it causes problems, we can still add more features, but I think I rather overdid it a bit in the past (with api-4-2-1 etc.)

[beicause]

@beicause could you for now limit this to 3 features?

The compiler invocation is already different due to --release flag, so it should be acceptable to add a --feature xy flag as well. If it causes problems, we can still add more features, but I think I rather overdid it a bit in the past (with api-4-2-1 etc.)

The problem is if you have already specified checks-x in Cargo.toml and then pass -r --features godot/checks-y, you will enable both checks-x and checks-y, which causes the build to fail.

[Yarwin]

Note – I was thinking earlier about exposing every safety level as an independent feature (the simplest possible implementation – no-checks-x, no-checks-y, no-checks-z) but unfortunately it causes a headache when combined with default features >:[.

[Bromeon]

The problem is if you have already specified checks-x in Cargo.toml and then pass -r --features godot/checks-y, you will enable both checks-x and checks-y, which causes the build to fail.

That is true, but the same happens with api-* features, no? Maybe here it's more common to want to specify one in Debug, one in Release though 🤔 maybe we should just bite the bullet and provide 6 more features 😞

[Bromeon]

As some stuff isn't yet clear and this can be added in a non-breaking way, I'll postpone this to after the initial v0.4 release.

[beicause]

I think we can just add two features: debug-checks-balanced and release-checks-fast-unsafe, and by default we use debug-checks-paranoid and release-checks-balanced. The other safety configs are probably not very useful.

[Bromeon]

Great idea! We can always add more if users have a concrete case for it 💪

[Bromeon]

Thanks for the update!

We should have some CI jobs that run itest with those features, otherwise we don't even know if code compiles, let alone it works.

Maybe we find a way to reuse existing CI jobs, so that total CI time isn't increased... Do you have any suggestions?

[Bromeon]

@beicause Not sure if you saw my review, do you think the suggestions make sense?

[beicause]

Maybe we find a way to reuse existing CI jobs, so that total CI time isn't increased... Do you have any suggestions?

I think CI already tested paranoid and balanced in debug build and release build.

Only fast unsafe is not tested, but I believe it won't pass many test cases in the itest.

[Yarwin]

CI already tested paranoid and balanced in debug build and release build.

True, we can see it in our CI 😄.
https://github.com/godot-rust/gdext/actions/runs/18426519635/job/52508379831?pr=1278
Initialize godot-rust (API v4.5.stable.official, runtime v4.5.stable.custom_build, safety checks paranoid/balanced)

Only fast unsafe is not tested, but I believe it won't pass many test cases in the itest.

True – and this should be covered, to inform what guarantees are and what aren't held on given check level (not including some tests with #[cfg(...)] should be enough 🤷). In general in itest one can see what works and what doesn't; if we don't cover release-checks-unsafe in our CI&tests, then the message we send is something along the lines of "idk man, maybe some things work, maybe some doesn't, go check for yourself, or maybe not, because itest will stumble on UB and crash".

I can cover them in separate PR.

Failing tests:

• object_engine_manual_double_free (instant UB and crash)
• base_smuggling (fail)
• object_user_call_after_free (fail)
• object_engine_use_after_free (fail)
• object_engine_use_after_free_varcall (fail)

As for test target itself – linux-release would be good I think?

IMO (I don't strive to be authoritative here) it is good to go, we can address itest tweaks to cover release-checks-fast-unsafe in separate PR. I've been torturing this branch locally for some time and haven't noticed anything wrong (yet). Just rebase (there is one silly merge conflict).

[Bromeon]

I took this PR over and will have something working soon.

[Bromeon]

Implemented CI, simplified the #[cfg]s and adjusted the tests to work with the new classification. I updated the initial description with details. Some things (classification of operations, naming, ...) may still change.

Many thanks to @beicause for providing a solid base!