Add interfaces for Context and ContextKey (#820)

* Add `ContextKeyInterface`
* Add `ContextInterface`
* Combine `SpanBuilderInterface::setParent()` and `::setNoParent()`
* Remove `NullPropagator`
* Fix `Context::with()` typehint
* Remove `Context::withContextValue()` suggestion

Author: Nevay

Context.php

@@ -4,30 +4,31 @@
 
 namespace OpenTelemetry\Context;
 
+use function assert;
 use function spl_object_id;
 
 /**
  * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md#context
  */
-final class Context
+final class Context implements ContextInterface
 {
     /** @var ContextStorageInterface&ExecutionContextAwareInterface */
     private static ContextStorageInterface $storage;
 
     // Optimization for spans to avoid copying the context array.
-    private static ContextKey $spanContextKey;
+    private static ContextKeyInterface $spanContextKey;
     private ?object $span = null;
     /** @var array<int, mixed> */
     private array $context = [];
-    /** @var array<int, ContextKey> */
+    /** @var array<int, ContextKeyInterface> */
     private array $contextKeys = [];
 
     private function __construct()
     {
         self::$spanContextKey = ContextKeys::span();
     }
 
-    public static function createKey(string $key): ContextKey
+    public static function createKey(string $key): ContextKeyInterface
     {
         return new ContextKey($key);
     }
@@ -51,17 +52,29 @@ public static function storage(): ContextStorageInterface
         return self::$storage ??= new ContextStorage();
     }
 
+    /**
+     * @param ContextInterface|false|null $context
+     *
+     * @internal
+     */
+    public static function resolve($context, ?ContextStorageInterface $contextStorage = null): ContextInterface
+    {
+        return $context
+            ?? ($contextStorage ?? self::storage())->current()
+            ?: self::getRoot();
+    }
+
     /**
      * @internal
      */
-    public static function getRoot(): Context
+    public static function getRoot(): ContextInterface
     {
         static $empty;
 
         return $empty ??= new self();
     }
 
-    public static function getCurrent(): Context
+    public static function getCurrent(): ContextInterface
     {
         return self::storage()->current();
     }
@@ -75,12 +88,12 @@ public function activate(): ScopeInterface
         return $scope;
     }
 
-    public function withContextValue(ImplicitContextKeyedInterface $value): Context
+    public function withContextValue(ImplicitContextKeyedInterface $value): ContextInterface
     {
         return $value->storeInContext($this);
     }
 
-    public function with(ContextKey $key, $value): self
+    public function with(ContextKeyInterface $key, $value): self
     {
         if ($this->get($key) === $value) {
             return $this;
@@ -108,9 +121,10 @@ public function with(ContextKey $key, $value): self
         return $self;
     }
 
-    public function get(ContextKey $key)
+    public function get(ContextKeyInterface $key)
     {
         if ($key === self::$spanContextKey) {
+            /** @psalm-suppress InvalidReturnStatement */
             return $this->span;
         }
 

ContextInterface.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Context;
+
+interface ContextInterface
+{
+    /**
+     * @param non-empty-string $key
+     *
+     * @see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.6.1/specification/context/context.md#create-a-key
+     */
+    public static function createKey(string $key): ContextKeyInterface;
+
+    public static function getCurrent(): ContextInterface;
+
+    /**
+     * Makes `$this` the currently active {@see ContextInterface}.
+     */
+    public function activate(): ScopeInterface;
+
+    /**
+     * This adds a key/value pair to this Context.
+     *
+     * @psalm-template T
+     * @psalm-param ContextKeyInterface<T> $key
+     * @psalm-param T|null $value
+     */
+    public function with(ContextKeyInterface $key, $value): ContextInterface;
+
+    public function withContextValue(ImplicitContextKeyedInterface $value): ContextInterface;
+
+    /**
+     * Fetch a value from the Context given a key value.
+     *
+     * @psalm-template T
+     * @psalm-param ContextKeyInterface<T> $key
+     * @psalm-return T|null
+     */
+    public function get(ContextKeyInterface $key);
+}

ContextKey.php

@@ -4,7 +4,10 @@
 
 namespace OpenTelemetry\Context;
 
-final class ContextKey
+/**
+ * @internal
+ */
+final class ContextKey implements ContextKeyInterface
 {
     private ?string $name;
 

ContextKeyInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Context;
+
+/**
+ * @template-covariant T
+ */
+interface ContextKeyInterface
+{
+}

ContextKeys.php

@@ -9,14 +9,14 @@
  */
 final class ContextKeys
 {
-    public static function span(): ContextKey
+    public static function span(): ContextKeyInterface
     {
         static $instance;
 
         return $instance ??= Context::createKey('opentelemetry-trace-span-key');
     }
 
-    public static function baggage(): ContextKey
+    public static function baggage(): ContextKeyInterface
     {
         static $instance;
 

ContextStorage.php

@@ -41,12 +41,12 @@ public function scope(): ?ContextStorageScopeInterface
             : null;
     }
 
-    public function current(): Context
+    public function current(): ContextInterface
     {
         return $this->current->node->context ?? Context::getRoot();
     }
 
-    public function attach(Context $context): ContextStorageScopeInterface
+    public function attach(ContextInterface $context): ContextStorageScopeInterface
     {
         return $this->current->node = new ContextStorageNode($context, $this->current, $this->current->node);
     }

ContextStorageInterface.php

@@ -8,7 +8,7 @@ interface ContextStorageInterface
 {
     public function scope(): ?ContextStorageScopeInterface;
 
-    public function current(): Context;
+    public function current(): ContextInterface;
 
-    public function attach(Context $context): ContextStorageScopeInterface;
+    public function attach(ContextInterface $context): ContextStorageScopeInterface;
 }

ContextStorageNode.php

@@ -11,13 +11,13 @@
  */
 final class ContextStorageNode implements ScopeInterface, ContextStorageScopeInterface
 {
-    public Context $context;
+    public ContextInterface $context;
     public ContextStorageHead $head;
     private ?ContextStorageNode $previous;
     private array $localStorage = [];
 
     public function __construct(
-        Context $context,
+        ContextInterface $context,
         ContextStorageHead $head,
         ?ContextStorageNode $previous = null
     ) {
@@ -50,7 +50,7 @@ public function offsetUnset($offset): void
         unset($this->localStorage[$offset]);
     }
 
-    public function context(): Context
+    public function context(): ContextInterface
     {
         return $this->context;
     }

ContextStorageScopeInterface.php

@@ -8,7 +8,7 @@
 
 interface ContextStorageScopeInterface extends ScopeInterface, ArrayAccess
 {
-    public function context(): Context;
+    public function context(): ContextInterface;
 
     /**
      * @param string $offset

FiberBoundContextStorage.php

@@ -57,14 +57,14 @@ public function scope(): ?ContextStorageScopeInterface
         return new FiberBoundContextStorageScope($scope);
     }
 
-    public function current(): Context
+    public function current(): ContextInterface
     {
         $this->checkFiberMismatch();
 
         return $this->storage->current();
     }
 
-    public function attach(Context $context): ContextStorageScopeInterface
+    public function attach(ContextInterface $context): ContextStorageScopeInterface
     {
         $scope = $this->storage->attach($context);
         assert(class_exists(Fiber::class, false));