This feels a bit better

servicetalk-client-api/src/main/java/io/servicetalk/client/api/ServiceDiscovererEvent.java

@@ -16,12 +16,14 @@
 package io.servicetalk.client.api;
 
 import java.util.Locale;
+import java.util.Map;
 
 /**
  * Notification from the Service Discovery system that availability for an address has changed.
  * @param <ResolvedAddress> the type of address after resolution.
  */
 public interface ServiceDiscovererEvent<ResolvedAddress> {
+
     /**
      * Get the resolved address which is the subject of this event.
      * <p>
@@ -40,17 +42,12 @@ public interface ServiceDiscovererEvent<ResolvedAddress> {
     Status status();
 
     /**
-     * Meta-data associated with the specified address.
-     * <p>
-     * Metadata is data that is not strictly necessary for load balancing purposes but can be useful for making more
-     * intelligent decisions. As described in {@link #address()}, updates to an addresses meta-data can be accomplished
-     * by sending another {@link ServiceDiscovererEvent} with the same address and {@link Status} but with different
-     * metadata. This also means that updates to status must also propagate the desired meta-data state or the empty
-     * meta-data state is assumed.
-     * @return
+     * The raw meta-data associated with this ServiceDiscovererEvent.
+     * Note: the result will be an unmodifiable collection.
+     * @return the raw meta-data associated with this ServiceDiscovererEvent.
      */
-    default Metadata metadata() {
-        return DefaultMetadata.EMPTY_METADATA;
+    default Map<String, Object> metadata() {
+        return ServiceDiscovererMetadata.EMPTY_MAP;
     }
 
     /**

servicetalk-client-api/src/main/java/io/servicetalk/client/api/ServiceDiscovererMetadata.java

@@ -0,0 +1,91 @@
+package io.servicetalk.client.api;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Utilities helpful for extracting meta-data from {@link ServiceDiscovererEvent}s.
+ */
+public final class ServiceDiscovererMetadata {
+
+    public static final Map<String, Object> EMPTY_MAP = Collections.unmodifiableMap(new HashMap<>(0));
+
+    /**
+     * Metadata that describes the relative weight of an endpoint.
+     */
+    public static final Key<Double> WEIGHT = new ServiceDiscovererMetadata.Key<>(Double.class, "endpoint.weight", 1.0);
+
+    /**
+     * Metadata describing the priority class of an endpoint.
+     */
+    public static final Key<Integer> PRIORITY = new ServiceDiscovererMetadata.Key<>(
+            Integer.class, "endpoint.priority", 0);
+
+    /**
+     * An extractor of meta-data to user with {@link ServiceDiscovererEvent} instances.
+     *
+     * A {@link ServiceDiscovererEvent} can carry additional metadata, but this data is not type safe. The key type
+     * exists to provide a uniform way to define meta-data extractors that can properly extract and cast meta-data
+     * while also providing a default.
+     * @param <T> the expected type of the meta-data.
+     */
+    public static final class Key<T> {
+
+        private final Class<T> clazz;
+        private final String name;
+        private final T defaultValue;
+
+        public Key(final Class<T> clazz, final String name, final T defaultValue) {
+            this.clazz = requireNonNull(clazz, "clazz");
+            this.name = requireNonNull(name, "name");
+            this.defaultValue = requireNonNull(defaultValue, "defaultValue");
+        }
+
+        public String name() {
+            return name;
+        }
+
+        public Class<T> clazz() {
+            return clazz;
+        }
+
+        public <T> boolean exists(ServiceDiscovererEvent<?> event) {
+            return event.metadata().containsKey(name);
+        }
+
+        public T getValue(ServiceDiscovererEvent<?> event) {
+            Object result = event.metadata().get(name);
+            if (clazz.isInstance(result)) {
+                return (T) result;
+            } else {
+                return defaultValue;
+            }
+        }
+
+        @Override
+        public int hashCode() {
+            return name.hashCode();
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            if (obj == null || obj.getClass() != Key.class) {
+                return false;
+            }
+            Key<?> other = (Key<?>) obj;
+            return other.clazz.equals(clazz) && other.name.equals(name);
+        }
+
+        @Override
+        public String toString() {
+            return "Key<" + clazz.getName() + ">(" + name + ", " + defaultValue + ")";
+        }
+    }
+
+    private ServiceDiscovererMetadata() {
+        // no instances.
+    }
+}

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/DefaultLoadBalancer.java

@@ -17,7 +17,6 @@
 
 import io.servicetalk.client.api.ConnectionFactory;
 import io.servicetalk.client.api.LoadBalancedConnection;
-import io.servicetalk.client.api.MetadataKeys;
 import io.servicetalk.client.api.NoActiveHostException;
 import io.servicetalk.client.api.NoAvailableHostException;
 import io.servicetalk.client.api.ServiceDiscovererEvent;
@@ -53,7 +52,7 @@
 
 import static io.servicetalk.client.api.LoadBalancerReadyEvent.LOAD_BALANCER_NOT_READY_EVENT;
 import static io.servicetalk.client.api.LoadBalancerReadyEvent.LOAD_BALANCER_READY_EVENT;
-import static io.servicetalk.client.api.MetadataKeys.WEIGHT;
+import static io.servicetalk.client.api.ServiceDiscovererMetadata.WEIGHT;
 import static io.servicetalk.client.api.ServiceDiscovererEvent.Status.AVAILABLE;
 import static io.servicetalk.client.api.ServiceDiscovererEvent.Status.EXPIRED;
 import static io.servicetalk.client.api.ServiceDiscovererEvent.Status.UNAVAILABLE;
@@ -311,7 +310,7 @@ private void sequentialOnNext(Collection<? extends ServiceDiscovererEvent<Resolv
                     } else {
                         // It's a new host, so the set changed.
                         hostSetChanged = true;
-                        nextHosts.add(createHost(event.address(), event.metadata().get(WEIGHT)));
+                        nextHosts.add(createHost(event.address(), WEIGHT.getValue(event)));
                     }
                 } else if (EXPIRED.equals(event.status())) {
                     if (!host.markExpired()) {
@@ -338,7 +337,7 @@ private void sequentialOnNext(Collection<? extends ServiceDiscovererEvent<Resolv
                 if (AVAILABLE.equals(event.status())) {
                     sendReadyEvent = true;
                     hostSetChanged = true;
-                    nextHosts.add(createHost(event.address(), event.metadata().get(WEIGHT)));
+                    nextHosts.add(createHost(event.address(), WEIGHT.getValue(event)));
                 }
             }