feat: EXC-2060: Introduce environment variables

[AlexandraZapuc]

Canister environment variables doc

This PR introduces environment variables for canisters. It adds support for environment variables in canister settings, allowing runtime configuration without code changes.

Changes

1. Added new Candid types:

• environment_variables record containing key-value pairs
• New variant in change_details for tracking environment variable changes

2. Extended canister settings:

• Added environment_variables field to canister_settings and definite_canister_settings

3. Added System APIs for environment variable access:

• ic0.env_var_count
• ic0.env_var_name_size
• ic0.env_var_name_copy
• ic0.env_var_value_size
• ic0.env_var_value_copy

4. Updated canister history tracking:

• Added environment_variables_change variant storing SHA-256 hash
• Multiple changes (controllers + env vars) can be recorded in single update

TODO: add changelog

* Added support for canister environment variables in canister settings
* New System API for accessing environment variables:
- ic0.env_var_count
- ic0.env_var_name_size
- ic0.env_var_name_copy
- ic0.env_var_value_size
* New SettingChange variant in canister history setting details

[github-actions]

🤖 Here's your preview: https://qslrt-byaaa-aaaam-aejga-cai.icp0.io

[letmejustputthishere]

this sounds pretty cool, where can i learn more about it? searching on slack or drive didn't yield any results :(
EDIT: found this

[mraszyk]

To avoid the conflicts:

• defer updating the changelog to the point the PR is just about to be merged;
• do not change column alignment in the system API matrix for system APIs not introduced here.

[skilesare]

Just as documentation, I've updated ICRC-105 to specify how to handle environment variable and their changes. Ideally(as with other replica changes) we'd love a lifecycle event to make this much less complicated to track. While I see that the hash of these changes are covered in the canister history API, the aim of 105 is to make full transparency of all config(software or environment variables), installs, configs, etc first class citizens in the ICRC-3 log. Enumeration is not a must as hopefully the developer knows which variables he is using and can review any changes to the hash, but enumeration would certainly be welcome. See more: dfinity/ICRC#105

[mraszyk]

enumeration would certainly be welcome

Depending on the size limits on canister environment variables, this could bloat up the canister history size substantially. Hence, a hash is preferrable (analogously to the WASM module hash that must also be reproduced separately).

[mraszyk]

we'd love a lifecycle event to make this much less complicated to track

What do you mean more concretely? And what would the workflow look like?

[skilesare]

What do you mean more concretely? And what would the workflow look like?

From:
https://forum.dfinity.org/t/canister-lifecycle-hooks/17089/38?u=skilesare

While we are here, there are a number of 'other' hooks that would be very helpful and one topic that would be worth discussing here in regards to the work I've been doing on ICRC-105. dfinity/ICRC#105

The 'spirit' of ICRC-105 is to give public utility canisters a spot in the ICRC-3 log to record any configuration, upgrade, or installation changes that may be relevant to the execution of the canister. The ideal 'best-case' scenario would be that given an ICRC-105 + ICRC-3 canister, the set of used wasms, properly recorded ICRC-3 block(proper being that they recorded all information relevant to the deterministic execution program/state changes) that one could reconstruct the state of the canister from the ICRC-3 log. This means we need to record any change to the canister the would affect how the code runs. Since you can write any code there may be a number of unknown unknowns that a dev would be responsible for, but it would be nice to take care of the known possible changes via canister life cycle events.

The obvious events would be

• Change of Controller(give me the new list)
• Change of canister settings(like compute_allocation, memory_allocation, freezing_threshold, reserved_cycles_limit, wasm_memory_limit, log_visibility (give me the new setting)
• A canister freeze(let this run once if my canister is frozen)
• A change of the environment variables(I understand this is under development) (let me enumerate the items or give them to me)
• A subnet change(when subnet migration is possible)(new subnet id)
• Edit: Canister Installed/upgraded (give me the new hash) - right now I have to do an timer+async call from my initializer and it delays and theoretically, something else could get called before I log the new hash...thus I have two blocks, one to record the install/upgrade and then a follow on to record the new hash.

One that is not so obvious would be something that fires if the version of the replica changes. I'm not sure what the process or workflow is there, but I would imagine that if a replica version is updated it might include code that could change the way a canister behaves(something like the cycle cost of certain operations or even system API level information). It may not be a great feature to have every canister on the subnet firing an event each time a new replica version starts up, but perhaps this could fire the first time that canister is called in the future?

[AlexandraZapuc]

@skilesare Thanks for your input. We’ll keep it in mind as feedback for future development. However, at this stage, it falls outside the scope of this specific feature.