Implement typed publish-only database environments

Cargo.toml

@@ -46,6 +46,7 @@ members = [
   "modules/keynote-benchmarks",
   "modules/perf-test",
   "modules/module-test",
+  "modules/environment-test",
   "templates/basic-rs/spacetimedb",
   "templates/chat-console-rs/spacetimedb",
   "modules/sdk-test",

crates/bindings-cpp/CMakeLists.txt

@@ -28,6 +28,33 @@ add_library(spacetimedb::spacetimedb_cpp_library ALIAS spacetimedb_cpp_library)
 
 target_sources(spacetimedb_cpp_library PRIVATE ${LIBRARY_SOURCES})
 
+# A declared Environment adds named methods to the context member type. Every
+# SDK and module translation unit must see the same prelude before any context.
+if(NOT DEFINED SPACETIMEDB_ENV_HEADER)
+    set(SPACETIMEDB_ENV_HEADER "" CACHE FILEPATH "Absolute module environment declaration header")
+endif()
+if(SPACETIMEDB_ENV_HEADER)
+    if(NOT IS_ABSOLUTE "${SPACETIMEDB_ENV_HEADER}" OR NOT EXISTS "${SPACETIMEDB_ENV_HEADER}")
+        message(FATAL_ERROR "SPACETIMEDB_ENV_HEADER must name an existing absolute declaration header")
+    endif()
+    # The standalone WASI ABI shims have no context or Environment type. Their
+    # hand-written ABI declarations must not include the C++ standard library's
+    # WASI declarations through the module prelude.
+    set_source_files_properties(src/abi/wasi_shims.cpp PROPERTIES
+        COMPILE_DEFINITIONS SPACETIMEDB_WASI_SHIMS=1)
+    configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/include/spacetimedb/environment_prelude.h.in
+        ${CMAKE_CURRENT_BINARY_DIR}/include/spacetimedb/environment_prelude.h
+        @ONLY)
+    set(SPACETIMEDB_ENV_PRELUDE "${CMAKE_CURRENT_BINARY_DIR}/include/spacetimedb/environment_prelude.h")
+    target_compile_definitions(spacetimedb_cpp_library PUBLIC SPACETIMEDB_ENV_HEADER_ACTIVE=1)
+    if(MSVC)
+        target_compile_options(spacetimedb_cpp_library PUBLIC "/FI${SPACETIMEDB_ENV_PRELUDE}")
+    else()
+        target_compile_options(spacetimedb_cpp_library PUBLIC -include "${SPACETIMEDB_ENV_PRELUDE}")
+    endif()
+endif()
+
 # Require C++20 for consumers of this library without forcing global flags
 target_compile_features(spacetimedb_cpp_library PUBLIC cxx_std_20)
 target_compile_definitions(spacetimedb_cpp_library PRIVATE SPACETIMEDB_UNSTABLE_FEATURES)

crates/bindings-cpp/README.md

@@ -275,3 +275,51 @@ See the `modules/*-cpp/src/` directory for example modules:
 
 This library is part of the SpacetimeDB project. Please see the main repository for contribution guidelines.
 
+
+### Declared environment
+
+Declare the complete environment schema in a dedicated header, before other SDK
+includes. Values are supplied at publish time and are never embedded in this
+header. For example, `environment.h`:
+
+```cpp
+#pragma once
+#include <spacetimedb/environment_declaration.h>
+SPACETIMEDB_ENV(
+    (API_URL, std::string),
+    (MODE, std::string, ("prod", "dev")),
+    (LOG_LEVEL, std::optional<std::string>, ("info", "debug"))
+)
+```
+
+Select it in your project's `CMakeLists.txt` **before** adding the SDK directory:
+
+```cmake
+set(SPACETIMEDB_ENV_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/environment.h")
+add_subdirectory(path/to/bindings-cpp sdk)
+add_executable(my_module src/lib.cpp)
+target_link_libraries(my_module PRIVATE spacetimedb_cpp_library)
+```
+
+The SDK's CMake target includes the declaration header before every SDK and module
+translation unit that uses contexts. The standalone WASI ABI shim is excluded
+because it has no SDK context types. This keeps the context type consistent;
+including the header in only one source file is insufficient. The normal module
+source can then use the usual umbrella include:
+
+```cpp
+#include <spacetimedb.h>
+void example(SpacetimeDB::ReducerContext ctx) {
+    std::string mode = ctx.env.MODE();
+    std::optional<std::string> level = ctx.env.LOG_LEVEL();
+}
+```
+
+An empty `SPACETIMEDB_ENV()` or an omitted declaration selects an empty schema.
+`get`, C++ keywords, and names colliding with the accessor type do not create named
+methods; use the checked `ctx.env.get("get")` form for such declared names. Unknown
+keys fail at runtime, including when the module declares no environment variables.
+Only the host's root module entry may read environment values. Ordinary C++ helper
+calls retain their caller's host scope. Values are private, durable database configuration for secrets and other settings.
+Database owners and authorized collaborators can read them; module code can expose
+them through its own outputs.

crates/bindings-cpp/include/spacetimedb/abi/FFI.h

@@ -73,6 +73,7 @@ using ::identity;
 
 // ===== JWT =====
 using ::get_jwt;
+using ::env_get;
 
 // ===== Procedure Transactions =====
 using ::procedure_start_mut_tx;

crates/bindings-cpp/include/spacetimedb/abi/abi.h

@@ -39,6 +39,9 @@
 #define STDB_IMPORT_10_5(name) \
     __attribute__((import_module("spacetime_10.5"), import_name(#name))) extern
 
+#define STDB_IMPORT_10_6(name) \
+    __attribute__((import_module("spacetime_10.6"), import_name(#name))) extern
+
 // Import opaque types into global namespace for C compatibility
 using SpacetimeDB::Status;
 using SpacetimeDB::TableId;
@@ -59,6 +62,9 @@ using SpacetimeDB::ConsoleTimerId;
 
 extern "C" {
 
+STDB_IMPORT_10_6(env_get)
+Status env_get(const uint8_t* key, uint32_t key_len, BytesSource* out);
+
 // ===== Table and Index Management =====
 STDB_IMPORT(table_id_from_name)
 Status table_id_from_name(const uint8_t* name_ptr, size_t name_len, TableId* out);

crates/bindings-cpp/include/spacetimedb/bsatn/reader.h

@@ -124,10 +124,10 @@ namespace SpacetimeDB::bsatn {
         template<typename T>
         std::optional<T> read_optional() {
             uint8_t tag = read_u8();
-            if (tag == 0) {
-                return std::nullopt;
-            } else if (tag == 1) {
+            if (tag == 0) { // Some, matching the canonical BSATN option type.
                 return SpacetimeDB::bsatn::deserialize<T>(*this);
+            } else if (tag == 1) { // None.
+                return std::nullopt;
             } else {
                 std::abort(); // Invalid optional tag in BSATN deserialization
             }

crates/bindings-cpp/include/spacetimedb/environment.h

@@ -0,0 +1,107 @@
+#ifndef SPACETIMEDB_ENVIRONMENT_H
+#define SPACETIMEDB_ENVIRONMENT_H
+#include <spacetimedb/abi/FFI.h>
+#include <array>
+#include <optional>
+#include <spacetimedb/logger.h>
+#include <string>
+#include <string_view>
+#include <type_traits>
+#include <unordered_set>
+#include <spacetimedb/internal/autogen/EnvironmentDeclaration.g.h>
+
+namespace SpacetimeDB {
+/// Read-only database environment. Reads use the current transaction, or a
+/// short snapshot in a procedure outside a transaction. Values are not cached.
+class EnvironmentBase {
+public:
+    std::optional<std::string> get(std::string_view key) const {
+        if (key.empty() || key.size() > 256) LOG_PANIC("invalid environment variable name");
+        BytesSource source{0};
+        if (FFI::env_get(reinterpret_cast<const uint8_t*>(key.data()), static_cast<uint32_t>(key.size()), &source) != Status(0))
+            LOG_PANIC("environment read failed");
+        if (source == BytesSource{0}) return std::nullopt;
+        std::array<uint8_t, 1024> buffer;
+        std::string value;
+        for (;;) {
+            size_t len = buffer.size();
+            const auto status = FFI::bytes_source_read(source, buffer.data(), &len);
+            if ((status != 0 && status != -1) || len > buffer.size()) LOG_PANIC("environment source read failed");
+            value.append(reinterpret_cast<const char*>(buffer.data()), len);
+            if (status == -1) return value;
+            if (len == 0) LOG_PANIC("environment source made no progress");
+        }
+    }
+};
+
+namespace Internal {
+inline std::vector<EnvironmentDeclaration>& environment_declarations() {
+    static std::vector<EnvironmentDeclaration> declarations;
+    return declarations;
+}
+
+template<typename T>
+inline constexpr bool environment_string = std::is_same_v<T, std::string> || std::is_same_v<T, std::optional<std::string>>;
+
+template<typename T>
+T read_environment(std::string_view key) {
+    static_assert(environment_string<T>, "Environment declarations require string or optional<string>");
+    auto value = EnvironmentBase{}.get(key);
+    if constexpr (std::is_same_v<T, std::string>) {
+        if (!value) LOG_PANIC("required environment value is absent");
+        return std::move(*value);
+    } else { return value; }
+}
+
+template<typename T>
+EnvironmentDeclaration declare_environment(std::string name) {
+    static_assert(environment_string<T>, "Environment declarations require string or optional<string>");
+    EnvironmentConstraint constraint;
+    constraint.set<0>(std::monostate{});
+    return {std::move(name), std::move(constraint), std::is_same_v<T, std::optional<std::string>>};
+}
+
+// Preserve the complete source literal, including embedded NUL bytes. Implicit
+// conversion through std::string(const char*) would truncate those constraints.
+struct EnvironmentLiteral {
+    std::string value;
+    template<size_t N>
+    EnvironmentLiteral(const char (&text)[N]) : value(text, N - 1) {}
+    EnvironmentLiteral(std::string text) : value(std::move(text)) {}
+};
+
+template<typename T>
+EnvironmentDeclaration declare_environment(std::string name, std::initializer_list<EnvironmentLiteral> allowed) {
+    auto declaration = declare_environment<T>(std::move(name));
+    if (allowed.size() == 0) LOG_PANIC("environment literal union cannot be empty");
+    std::unordered_set<std::string> unique;
+    std::vector<std::string> values;
+    values.reserve(allowed.size());
+    for (const auto& literal : allowed) {
+        const auto& value = literal.value;
+        if (value.size() > 8192 || !unique.insert(value).second) LOG_PANIC("invalid environment literal union");
+        values.push_back(value);
+    }
+    if (values.size() == 1) declaration.constraint.template set<1>(std::move(values.front()));
+    else declaration.constraint.template set<2>(std::move(values));
+    return declaration;
+}
+
+inline void validate_environment_declarations() {
+    const auto& declarations = environment_declarations();
+    if (declarations.size() > 256) LOG_PANIC("too many environment declarations");
+    std::unordered_set<std::string> keys;
+    const auto initial = [](char c) { return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c == '_'; };
+    for (const auto& declaration : declarations) {
+        const auto& key = declaration.name;
+        if (key.empty() || key.size() > 256 || !initial(key[0]) || !keys.insert(key).second) LOG_PANIC("invalid environment declaration name");
+        for (char c : key) if (!initial(c) && !(c >= '0' && c <= '9')) LOG_PANIC("invalid environment declaration name");
+    }
+}
+}
+
+#ifndef SPACETIMEDB_ENV_DECLARATION
+class Environment : public EnvironmentBase {};
+#endif
+}
+#endif