Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
import java.util.Set;

/**
Expand All @@ -20,6 +21,9 @@
* nested collections with the source's entity, and the layer never writes to them. The source's
* entity is never marked, so a source may retain the entities it supplied and supply them again.
* <p>
* The layer never holds a deleted item. Serving one would hide the LaunchDarkly data for its key,
* but an override only adds or replaces definitions, so a replacement that contains one is rejected.
* <p>
* This class is package-private and should not be used by application code.
*/
final class OverrideLayer implements DataModelDependencies.ExternalDependencies {
Expand Down Expand Up @@ -50,11 +54,62 @@ static final class Replacement {
// segments. Rebuilt with the contents on every replacement and swapped with them.
private volatile DataModelDependencies.DependencyTracker dependencies = new DataModelDependencies.DependencyTracker();

/**
* Thrown by {@link OverrideLayer#setAll(Iterable)} when the data contains an item that the layer
* cannot hold. The data is rejected as a whole and the layer is unchanged.
*/
static class RejectedItemException extends IllegalArgumentException {
private static final long serialVersionUID = 1L;

RejectedItemException(String message) {
super(message);
}
}

/**
* Thrown when the data contains a deleted item. The layer never holds one.
*/
static final class DeletedItemException extends RejectedItemException {
private static final long serialVersionUID = 1L;

DeletedItemException(DataKind kind, String key) {
super(describeKind(kind) + " \"" + key + "\" is marked as deleted");
}
}

/**
* Thrown when the data lists a flag or segment under a key other than the definition's own key.
* Evaluation reads an entry by the key it is listed under, while the all flags state and events
* report the definition's key, so such an entry would be served under one key and reported under
* the other.
*/
static final class MismatchedKeyException extends RejectedItemException {
private static final long serialVersionUID = 1L;

MismatchedKeyException(DataKind kind, String key, String definitionKey) {
super(describeKind(kind) + " \"" + key + "\" has the key "
+ (definitionKey == null ? "null" : "\"" + definitionKey + "\"")
+ "; the key of each definition must be its key in the snapshot");
}
}

private static String describeKind(DataKind kind) {
if (kind == DataModel.FEATURES) {
return "flag";
}
if (kind == DataModel.SEGMENTS) {
return "segment";
}
return "item of kind " + (kind == null ? "null" : kind.getName());
}

/**
* Atomically replaces the entire layer contents. A null or empty collection clears the layer.
*
* @param data the complete set of entries, grouped by data kind
* @return the previous and the new contents
* @throws RejectedItemException if the data contains a deleted item, or a flag or segment listed
* under a key other than its own; the layer is unchanged
*/
Replacement setAll(Iterable<Map.Entry<DataKind, KeyedItems<ItemDescriptor>>> data) {
Map<DataKind, Map<String, ItemDescriptor>> collected = new HashMap<>();
Expand All @@ -69,6 +124,17 @@ Replacement setAll(Iterable<Map.Entry<DataKind, KeyedItems<ItemDescriptor>>> dat
continue;
}
for (Map.Entry<String, ItemDescriptor> item : kindItems) {
// Nothing is swapped in until every entry is collected, so a rejection leaves the layer as
// it was.
if (isDeleted(item.getValue())) {
throw new DeletedItemException(kindEntry.getKey(), item.getKey());
}
Object entity = item.getValue() == null ? null : item.getValue().getItem();
if (entity instanceof DataModel.VersionedData
&& !Objects.equals(((DataModel.VersionedData) entity).getKey(), item.getKey())) {
throw new MismatchedKeyException(kindEntry.getKey(), item.getKey(),
((DataModel.VersionedData) entity).getKey());
}
ItemDescriptor copied = markedCopy(item.getValue());
items.put(item.getKey(), copied);
tracker.updateDependenciesFrom(kindEntry.getKey(), item.getKey(), copied);
Expand Down Expand Up @@ -137,8 +203,20 @@ boolean isEmpty() {
return !nonEmpty;
}

// Reports whether a descriptor is a deleted item: the placeholder with no item, which
// DataKind.deserialize produces for a definition marked as deleted, or a flag or segment that is
// marked as deleted.
private static boolean isDeleted(ItemDescriptor item) {
if (item == null) {
return false;
}
Object entity = item.getItem();
return entity == null
|| (entity instanceof DataModel.VersionedData && ((DataModel.VersionedData) entity).isDeleted());
}

// Returns a copy of the descriptor whose item carries the override marker. An item of another
// type, or a deleted item placeholder, is returned as is.
// type is returned as is.
static ItemDescriptor markedCopy(ItemDescriptor item) {
Object entity = item.getItem();
if (entity instanceof FeatureFlag) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,14 +61,23 @@ final class OverrideSinkImpl implements OverrideSink {
* Atomically replaces the entire override layer, then notifies listeners of every flag whose
* merged-view evaluation may have changed. Calls are serialized, so overlapping updates from a
* source cannot interleave.
* <p>
* A snapshot that contains a deleted item, or a flag or segment listed under a key other than its
* own, is rejected as a whole: the error is logged, the layer keeps its contents, and no listener
* is notified.
*/
@Override
public synchronized void setOverrides(Iterable<Map.Entry<DataKind, KeyedItems<ItemDescriptor>>> data) {
if (closed) {
logger.debug("Ignoring an override snapshot supplied after the override source was closed");
return;
}
apply(data);
try {
apply(data);
} catch (OverrideLayer.RejectedItemException e) {
logger.error("Rejected an override snapshot because {}; the overrides in effect are unchanged",
e.getMessage());
}
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -95,15 +95,18 @@ private FileOverrides() {}
* {@link com.launchdarkly.sdk.server.LDClient#allFlagsState} with
* {@link com.launchdarkly.sdk.server.FlagsStateOption#CLIENT_SIDE_ONLY} leaves it out, even when
* the flag it overrides is available to them. To override such a flag, define it in
* {@code "flags"} with {@code "clientSide": true}.
* {@code "flags"} with {@code "clientSide": true}. A flag or segment is listed under its key: a
* {@code "key"} property inside the definition is optional, and the key it is listed under is the
* one that is used.
* When multiple files are configured, their entries are combined in the configured order, and
* the duplicate keys handling decides which file wins for a key that appears more than once.
* <p>
* A reload replaces the entire override set, so removing an entry from the files removes the
* override. A configured file that does not exist contributes no overrides, so deleting every file
* removes them all. A file that exists but cannot be read or parsed makes the reload fail: the
* overrides in effect stay, the source logs the failure, and it recovers on its own once the file
* can be read again.
* can be read again. A file that contains an entry marked as deleted fails to load in the same way;
* to remove an override, remove its entry or delete the file.
* <p>
* Files can be rewritten in place: if the source finds a file empty while it is being rewritten, it
* keeps the overrides in effect until the new content is written. To remove a file's overrides,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

import com.google.common.collect.ImmutableList;
import com.launchdarkly.sdk.LDValue;
import com.launchdarkly.sdk.LDValueType;
import com.launchdarkly.sdk.ObjectBuilder;
import com.launchdarkly.sdk.server.integrations.FileDataReloader.EmptiedFileException;
import com.launchdarkly.sdk.server.integrations.FileDataSourceParsing.FileDataException;
import com.launchdarkly.sdk.server.integrations.FileDataSourceParsing.FlagFactory;
Expand Down Expand Up @@ -40,8 +42,9 @@
* This loader is separate from the file data source's loader because the override source has
* different rules: a configured file that does not exist contributes no entries, entries keep the
* versions that the documents specify, a value-only entry becomes a flag that is on and serves the
* value by fallthrough, the format of a file is chosen by its extension, and every failure to read or
* parse a file is reported as a file data error. The file data source keeps its own behavior.
* value by fallthrough, the format of a file is chosen by its extension, a flag or segment entry that
* is marked as deleted fails the load, and every failure to read or parse a file is reported as a file
* data error. The file data source keeps its own behavior.
* <p>
* Whether a file with no content is valid depends on its format, like the rest of its content. A JSON
* file with no content is not a JSON document, so it fails to parse. A YAML file with no content is a
Expand Down Expand Up @@ -426,7 +429,8 @@ private int[] addEntries(Map<DataKind, Map<String, ItemDescriptor>> data, Path p
try {
if (document.flags != null) {
for (Map.Entry<String, LDValue> e : document.flags.entrySet()) {
if (add(data, FEATURES, e.getKey(), FlagFactory.flagFromJson(e.getValue()))) {
ItemDescriptor flag = notDeleted("flag", e.getKey(), FlagFactory.flagFromJson(keyedBy(e.getKey(), e.getValue())));
if (add(data, FEATURES, e.getKey(), flag)) {
flagsAdded++;
}
}
Expand All @@ -440,7 +444,9 @@ private int[] addEntries(Map<DataKind, Map<String, ItemDescriptor>> data, Path p
}
if (document.segments != null) {
for (Map.Entry<String, LDValue> e : document.segments.entrySet()) {
if (add(data, SEGMENTS, e.getKey(), FlagFactory.segmentFromJson(e.getValue()))) {
ItemDescriptor segment = notDeleted("segment", e.getKey(),
FlagFactory.segmentFromJson(keyedBy(e.getKey(), e.getValue())));
if (add(data, SEGMENTS, e.getKey(), segment)) {
segmentsAdded++;
}
}
Expand All @@ -456,6 +462,37 @@ private int[] addEntries(Map<DataKind, Map<String, ItemDescriptor>> data, Path p
return new int[] { flagsAdded, segmentsAdded };
}

// A flag or segment entry is keyed by the key it is listed under, as the other SDKs' override
// sources key it: a key property inside the entry is set to that key. Evaluation reads an entry by
// the key it is listed under, while the all flags state and events report the definition's own key,
// so an entry pasted under a new key with its old key property would otherwise be served under one
// key and reported under the other, and an entry without a key property would have no key. An entry
// that is not an object is left as it is, so that it fails to parse.
private static LDValue keyedBy(String key, LDValue entry) {
if (entry.getType() != LDValueType.OBJECT) {
return entry;
}
ObjectBuilder builder = LDValue.buildObject();
for (String property : entry.keys()) {
if (!property.equals("key")) {
builder.put(property, entry.get(property));
}
}
return builder.put("key", key).build();
}

// A definition marked as deleted deserializes to a deleted item placeholder. In an override file it
// is a mistake, not a way to remove an override, which is done by removing the entry, so it fails the
// load like a file that cannot be parsed. It fails even when the duplicate keys handling would drop
// the entry, because the file still needs correcting. The file data source keeps accepting it.
private static ItemDescriptor notDeleted(String kind, String key, ItemDescriptor item) throws FileDataException {
if (item.getItem() == null) {
throw new FileDataException(kind + " \"" + key + "\" is marked as deleted; remove the entry to remove its override",
null);
}
return item;
}

/**
* Records that the result of a load is now the data in effect: it was applied, or it was skipped
* because it is unchanged. Whether each file contributed content to the data in effect decides
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,10 @@ public interface OverrideSink {
* and {@link com.launchdarkly.sdk.server.DataModel#SEGMENTS}, with item descriptors whose items
* are the SDK's flag and segment model objects, as produced by
* {@link DataKind#deserialize(String)}. Sources supply ordinary, fully parsed entities. The SDK
* itself marks the entries as overrides. The source's objects are never modified.
* itself marks the entries as overrides. The source's objects are never modified. Each flag and
* segment must be listed under its own key. A snapshot that contains a deleted flag or segment, or
* one listed under another key, is rejected as a whole: the SDK logs an error and the overrides in
* effect stay.
* <p>
* This method is safe to call from any thread. The SDK serializes calls, and the new layer
* contents are visible to evaluations when the call returns.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
import java.time.Duration;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
Expand Down Expand Up @@ -193,6 +194,27 @@ public void clientSideAllFlagsStateKeepsADefinitionWithClientSideButNotAFlagValu
}
}

@Test
public void fileEntryIsServedAndReportedUnderTheKeyItIsListedUnder() throws Exception {
// One entry has no key property and one has the key of the entry it was copied from. Both are
// evaluated, and reported in the all flags state, under the keys they are listed under.
try (TempDir dir = TempDir.create()) {
Path file = dir.getPath().resolve("overrides.json");
Files.write(file, ("{\"flags\": {"
+ "\"no-key\": {\"on\": true, \"variations\": [\"a\"], \"fallthrough\": {\"variation\": 0}},"
+ "\"copied\": {\"key\": \"original\", \"on\": true, \"variations\": [\"b\"], \"fallthrough\": {\"variation\": 0}}"
+ "}}").getBytes(StandardCharsets.UTF_8));
try (LDClient client = new LDClient(SDK_KEY, uninitializedConfig(FileOverrides.source().filePaths(file)))) {
assertEquals("a", client.stringVariation("no-key", CONTEXT, "default"));
assertEquals("b", client.stringVariation("copied", CONTEXT, "default"));
Map<String, LDValue> values = new HashMap<>();
values.put("no-key", LDValue.of("a"));
values.put("copied", LDValue.of("b"));
assertEquals(values, client.allFlagsState(CONTEXT).toValuesMap());
}
}
}

@Test
public void allFlagsStateOverridesOnlyWarningIsLoggedOnce() throws Exception {
TestOverrideSource source = new TestOverrideSource(flagsOnly(valueFlag("overridden", "override-value")));
Expand Down
Loading
Loading