Line data    Source code

       1              : // Licensed under the Apache License, Version 2.0
       2              : // Copyright 2025, Michael Bushe, All rights reserved.
       3              : 
       4              : export 'environment_service_io.dart'
       5              :     if (dart.library.js_interop) 'environment_service_web.dart';
       6              : 
       7              : /// Interface for accessing environment variables in a platform-independent manner.
       8              : ///
       9              : /// The Dart platform respects POSIX environmental variables (env vars) while
      10              : /// also creating a second env var namespace when compiling or running with
      11              : /// --dart-define flags.
      12              : ///
      13              : /// The OpenTelemetry Specification requires the support of env vars. This Dart
      14              : /// implementation extends the meaning of env vars to include --dart-define
      15              : /// constants that are "baked into" the Dart compilation or interpreter.
      16              : ///
      17              : /// If a value is defined with --dart-define, it takes precedence over POSIX
      18              : /// env vars. If a value is not defined with --dart-define, the system env var
      19              : /// is used. If neither is defined, null is returned.
      20              : ///
      21              : /// For the web platform, only --dart-define values are available since
      22              : /// io.Platform is not accessible in browsers.
      23              : ///
      24              : /// Environment variable lookup priority (non-web):
      25              : /// 1. String.fromEnvironment (--dart-define values)
      26              : /// 2. io.Platform.environment (system environment variables)
      27              : ///
      28              : /// Environment variable lookup priority (web):
      29              : /// 1. String.fromEnvironment (--dart-define values only)
      30              : ///
      31              : /// Example usages:
      32              : /// ```bash
      33              : /// # Using system environment variables (non-web only)
      34              : /// export OTEL_SERVICE_NAME=my-app
      35              : /// dart run
      36              : ///
      37              : /// # Using --dart-define (works on all platforms including web)
      38              : /// flutter run --dart-define=OTEL_SERVICE_NAME=my-app \
      39              : ///             --dart-define=OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
      40              : ///
      41              : /// # Mixing both (--dart-define takes precedence)
      42              : /// export OTEL_SERVICE_NAME=from-env
      43              : /// dart run --dart-define=OTEL_SERVICE_NAME=from-dart-define
      44              : /// # Result: "from-dart-define" is used
      45              : /// ```
      46              : ///
      47              : abstract interface class EnvironmentServiceInterface {
      48            0 :   const EnvironmentServiceInterface._();
      49              : 
      50              :   /// Gets the value of an environment variable.
      51              :   ///
      52              :   /// Returns the value from the first available source based on platform.
      53              :   ///
      54              :   /// @param key The name of the environment variable to retrieve
      55              :   /// @return The value of the environment variable, or null if not found
      56              :   String? getValue(String key);
      57              : }