KnowledgeBaseDescriptor.java
/*
* Copyright © 2026 IKE Network (support@ike.network)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package network.ike.plugin;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Properties;
/**
* The knowledge-base descriptor: what a store is, in one small file a program managing stores reads
* without opening the store (the IKE Dashboard design, {@code dev-ike-dashboard} in ike-lab-documents).
* Every store {@code ike:kb-assemble} writes carries it with its icon:
*
* <pre>
* META-INF/ike/knowledge-base.properties descriptorLevel, coordinate, displayName, layout, …, icon,
* the collection, when it is in one, the memory the
* assembly measured, when it did, and the inputs it was
* assembled from
* META-INF/ike/icon.png, icon@2x.png the knowledge base's icon
* </pre>
*
* <p>Level {@value #LEVEL} requires every field this class writes but {@code resolvedVersion}, which
* a build knows only for a release, and the icon file at the path {@code icon} names. A project
* keeps its icon at {@value #ICON_SOURCE}; one that has none gets a monogram
* ({@link KnowledgeBaseMonogram}), so every store reaches level 1. The same descriptor and icon
* deploy beside the store zips as {@code properties:kb-descriptor} and {@code png:icon}.
*/
final class KnowledgeBaseDescriptor {
/** The descriptor, relative to the store root. */
static final String FILE = "META-INF/ike/knowledge-base.properties";
/** The icon, relative to the store root. */
static final String ICON = "META-INF/ike/icon.png";
/** Where a knowledge-base project keeps its icon, relative to its base directory. */
static final String ICON_SOURCE = "src/main/kb/icon.png";
/** The descriptor level this class writes. */
static final int LEVEL = 1;
/** The classifier the descriptor deploys under, extension {@code properties}. */
static final String CLASSIFIER = "kb-descriptor";
/** The classifier the icon deploys under, extension {@code png}. */
static final String ICON_CLASSIFIER = "icon";
/** What follows an export's name in the name of the record of its inputs. */
static final String INPUTS_SUFFIX = ".inputs.properties";
/**
* The memory facts the assembly reports in the store's manifest, by manifest attribute, and the
* descriptor entry each is carried in. They are optional at level {@value #LEVEL}; a program
* sizing a store's heap reads them from Nexus before the store is downloaded (the IKE Dashboard
* design, decision 10; IKE-Network/ike-issues#1324).
*/
static final Map<String, String> MEMORY = memoryEntries();
private static Map<String, String> memoryEntries() {
Map<String, String> entries = new LinkedHashMap<>();
entries.put("Ike-Stated-Axiom-Bytes", "statedAxiomBytes");
entries.put("Ike-Loaded-Heap-Bytes", "loadedHeapBytes");
entries.put("Ike-Reasoner-Heap-Bytes", "reasonerHeapBytes");
entries.put("Ike-Reasoner-Heap-Upper-Bytes", "reasonerHeapUpperBytes");
return java.util.Collections.unmodifiableMap(entries);
}
/** Who may download the knowledge base: anyone, or only those the restricted repositories admit. */
enum Access {
/** Served to anyone. */
PUBLIC,
/** Served only to those the restricted repositories admit, as licensed content requires. */
RESTRICTED;
String value() {
return name().toLowerCase(java.util.Locale.ROOT);
}
}
/**
* One input a store was assembled from, in the order kb-assemble took it, written as
* {@code input.<n>=<role> <reference>} with {@code input.<n>.resolvedVersion} and
* {@code input.<n>.importer} beside it when known. A program managing stores reads them to show
* which knowledge bases a store includes (decision 18 of the IKE Dashboard design).
*
* @param role how the assembly took it: {@code STORE_SEED}, {@code PB}, {@code CHANGESET}
* or {@code SOURCE}
* @param reference the Maven coordinate as the build wrote it
* ({@code g:a[:extension[:classifier]]:v}), or {@code file:<name>} for a file
* that is no artifact of a repository
* @param resolvedVersion the version the coordinate resolved to, when it differs from the one
* written: a snapshot's deploy
* @param importer a {@code SOURCE} input's importer
*/
record Input(String role, String reference, Optional<String> resolvedVersion, Optional<String> importer) {
}
/**
* What a build knows about the knowledge base, the same for every store it assembles.
*
* @param groupId the coordinate's groupId
* @param artifactId the coordinate's artifactId
* @param version the coordinate's version
* @param displayName the name a person reads, the project's {@code <name>}
* @param entityFormat the entity format the store was written in
* @param assembledAt when the store was assembled
* @param access who may download it
* @param memory what the assembly measured, by descriptor entry, in bytes ({@link #MEMORY})
* @param collection the collection the knowledge base belongs to, such as {@code SOLOR}: the
* knowledge bases one pipeline builds and publishes together, which a program
* managing stores keeps at hand without being told to (decision 17 of the
* IKE Dashboard design)
* @param inputs what the store was assembled from, in order
*/
record Fields(String groupId, String artifactId, String version, String displayName, int entityFormat,
Instant assembledAt, Access access, Map<String, Long> memory, Optional<String> collection,
List<Input> inputs) {
/**
* Copies the memory facts and the inputs, and takes a blank collection for none.
*
* @param groupId the coordinate's groupId
* @param artifactId the coordinate's artifactId
* @param version the coordinate's version
* @param displayName the name a person reads
* @param entityFormat the entity format the store was written in
* @param assembledAt when the store was assembled
* @param access who may download it
* @param memory what the assembly measured, by descriptor entry
* @param collection the collection the knowledge base belongs to
* @param inputs what the store was assembled from, in order
*/
Fields {
memory = java.util.Collections.unmodifiableMap(new LinkedHashMap<>(memory));
collection = collection.map(String::strip).filter(name -> !name.isEmpty());
inputs = List.copyOf(inputs);
}
/**
* Fields with no inputs recorded.
*
* @param groupId the coordinate's groupId
* @param artifactId the coordinate's artifactId
* @param version the coordinate's version
* @param displayName the name a person reads
* @param entityFormat the entity format the store was written in
* @param assembledAt when the store was assembled
* @param access who may download it
* @param memory what the assembly measured, by descriptor entry
* @param collection the collection the knowledge base belongs to
*/
Fields(String groupId, String artifactId, String version, String displayName, int entityFormat,
Instant assembledAt, Access access, Map<String, Long> memory, Optional<String> collection) {
this(groupId, artifactId, version, displayName, entityFormat, assembledAt, access, memory, collection,
List.of());
}
/**
* Fields of a knowledge base in no collection.
*
* @param groupId the coordinate's groupId
* @param artifactId the coordinate's artifactId
* @param version the coordinate's version
* @param displayName the name a person reads
* @param entityFormat the entity format the store was written in
* @param assembledAt when the store was assembled
* @param access who may download it
* @param memory what the assembly measured, by descriptor entry
*/
Fields(String groupId, String artifactId, String version, String displayName, int entityFormat,
Instant assembledAt, Access access, Map<String, Long> memory) {
this(groupId, artifactId, version, displayName, entityFormat, assembledAt, access, memory, Optional.empty());
}
/**
* Fields with no memory measured.
*
* @param groupId the coordinate's groupId
* @param artifactId the coordinate's artifactId
* @param version the coordinate's version
* @param displayName the name a person reads
* @param entityFormat the entity format the store was written in
* @param assembledAt when the store was assembled
* @param access who may download it
*/
Fields(String groupId, String artifactId, String version, String displayName, int entityFormat,
Instant assembledAt, Access access) {
this(groupId, artifactId, version, displayName, entityFormat, assembledAt, access, Map.of());
}
}
/**
* The memory facts among a store's manifest attributes, by descriptor entry; an attribute that is
* not a whole number of bytes is left out.
*
* @param attributes the manifest attributes the assembly reported
* @return the facts, in {@link #MEMORY}'s order
*/
static Map<String, Long> memory(Map<String, String> attributes) {
Map<String, Long> memory = new LinkedHashMap<>();
MEMORY.forEach((attribute, entry) -> {
String value = attributes.get(attribute);
if (value != null) {
try {
memory.put(entry, Long.parseLong(value.strip()));
} catch (NumberFormatException e) {
// not a size: the descriptor leaves it out
}
}
});
return memory;
}
private KnowledgeBaseDescriptor() {
}
/**
* The icon a knowledge-base project keeps at {@value #ICON_SOURCE}, when it has one.
*
* @param basedir the project's base directory
* @return the icon file, or empty when the project has none
*/
static Optional<Path> icon(Path basedir) {
return Optional.of(basedir.resolve(ICON_SOURCE)).filter(Files::isRegularFile);
}
/**
* The store's layout, from its files: {@code rocks}, {@code spined-32} or {@code spined-64}.
*
* @param store the store directory
* @return the layout
* @throws IOException if the store's files name no layout this descriptor level knows
*/
static String layout(Path store) throws IOException {
if (Files.isDirectory(store.resolve("rocks"))) {
return "rocks";
}
if (Files.isDirectory(store.resolve("nidToByteArrayMap"))) {
return "spined-32";
}
Path format = store.resolve("store-format.properties");
if (Files.isRegularFile(format)) {
Properties properties = new Properties();
try (InputStream in = Files.newInputStream(format)) {
properties.load(in);
}
if ("64-bit".equals(properties.getProperty("layout"))) {
return "spined-64";
}
}
throw new IOException("No layout the knowledge-base descriptor knows (rocks, spined-32, spined-64) in " + store);
}
/**
* The entity format a store's own files record, for a store whose assembly did not report one.
*
* @param store the store directory
* @return the entity format {@code store-format.properties} records, if it does
* @throws IOException if the file exists but cannot be read
*/
static Optional<Integer> recordedEntityFormat(Path store) throws IOException {
Path format = store.resolve("store-format.properties");
if (!Files.isRegularFile(format)) {
return Optional.empty();
}
Properties properties = new Properties();
try (InputStream in = Files.newInputStream(format)) {
properties.load(in);
}
try {
return Optional.ofNullable(properties.getProperty("entityFormat")).map(String::strip).map(Integer::valueOf);
} catch (NumberFormatException e) {
return Optional.empty();
}
}
/**
* Writes the descriptor and the icon into a store, replacing any an earlier build left.
*
* @param store the store directory
* @param fields what the build knows
* @param icon the icon to copy, with its {@code @2x} companion when there is one
* @return the descriptor file written
* @throws IOException if a file cannot be written, or the store names no known layout
*/
static Path write(Path store, Fields fields, Path icon) throws IOException {
Path storedIcon = store.resolve(ICON);
Files.createDirectories(storedIcon.getParent());
Files.deleteIfExists(storedIcon);
Files.deleteIfExists(doubleResolution(storedIcon));
Files.copy(icon, storedIcon);
if (Files.isRegularFile(doubleResolution(icon))) {
Files.copy(doubleResolution(icon), doubleResolution(storedIcon));
}
Map<String, String> entries = new LinkedHashMap<>();
entries.put("descriptorLevel", Integer.toString(LEVEL));
entries.put("groupId", fields.groupId());
entries.put("artifactId", fields.artifactId());
entries.put("version", fields.version());
if (!fields.version().endsWith("-SNAPSHOT")) {
// A snapshot's deploy is named only when it is deployed; a release is its own.
entries.put("resolvedVersion", fields.version());
}
entries.put("displayName", fields.displayName());
entries.put("layout", layout(store));
entries.put("entityFormat", Integer.toString(fields.entityFormat()));
entries.put("assembledAt", fields.assembledAt().toString());
entries.put("access", fields.access().value());
entries.put("icon", ICON);
fields.collection().ifPresent(collection -> entries.put("collection", collection));
fields.memory().forEach((entry, bytes) -> entries.put(entry, Long.toString(bytes)));
entries.putAll(inputEntries(fields.inputs()));
Path file = store.resolve(FILE);
Files.writeString(file, text(entries, "Knowledge-base descriptor, level " + LEVEL), StandardCharsets.ISO_8859_1);
return file;
}
/** The inputs as {@code input.<n>} entries, in order. */
private static Map<String, String> inputEntries(List<Input> inputs) {
Map<String, String> entries = new LinkedHashMap<>();
for (int i = 0; i < inputs.size(); i++) {
Input input = inputs.get(i);
String key = "input." + (i + 1);
entries.put(key, input.role() + " " + input.reference());
input.resolvedVersion().ifPresent(version -> entries.put(key + ".resolvedVersion", version));
input.importer().ifPresent(importer -> entries.put(key + ".importer", importer));
}
return entries;
}
/**
* The file beside an export that records what the export was assembled from:
* {@code <export's name>}{@value #INPUTS_SUFFIX}.
*
* @param export the export, such as a reasoned protobuf
* @return the record's path, whether or not it exists
*/
static Path inputsRecord(Path export) {
return export.resolveSibling(export.getFileName() + INPUTS_SUFFIX);
}
/**
* Records beside an export what it was assembled from, as the descriptor's {@code input.<n>}
* entries. A later assembly that loads the export reads the record, so the store it writes
* names the knowledge bases and sources it includes, not the export between them.
*
* @param export the export
* @param inputs what it was assembled from, in order
* @return the record written
* @throws IOException if the record cannot be written
*/
static Path writeInputs(Path export, List<Input> inputs) throws IOException {
Path record = inputsRecord(export);
Files.writeString(record, text(inputEntries(inputs), "What " + export.getFileName() + " was assembled from"),
StandardCharsets.ISO_8859_1);
return record;
}
/**
* What a file was assembled from, when an assembly recorded it beside the file.
*
* @param export the file
* @return the inputs in order, or empty when no record is beside it
* @throws IOException if the record exists but cannot be read
*/
static List<Input> recordedInputs(Path export) throws IOException {
Path record = inputsRecord(export);
if (!Files.isRegularFile(record)) {
return List.of();
}
Properties properties = new Properties();
try (InputStream in = Files.newInputStream(record)) {
properties.load(in);
}
List<Input> inputs = new ArrayList<>();
for (int n = 1; properties.getProperty("input." + n) != null; n++) {
String[] entry = properties.getProperty("input." + n).strip().split("\\s+", 2);
if (entry.length == 2) {
inputs.add(new Input(entry[0], entry[1],
Optional.ofNullable(properties.getProperty("input." + n + ".resolvedVersion")).map(String::strip),
Optional.ofNullable(properties.getProperty("input." + n + ".importer")).map(String::strip)));
}
}
return inputs;
}
/**
* The entries in order, escaped as {@link Properties#store(java.io.OutputStream, String)}
* escapes them, without its timestamp, so a rebuild writes the same bytes.
*/
private static String text(Map<String, String> entries, String comment) throws IOException {
StringBuilder text = new StringBuilder("#" + comment + "\n");
for (Map.Entry<String, String> entry : entries.entrySet()) {
Properties one = new Properties();
one.setProperty(entry.getKey(), entry.getValue());
ByteArrayOutputStream out = new ByteArrayOutputStream();
one.store(out, null);
out.toString(StandardCharsets.ISO_8859_1).lines().filter(line -> !line.startsWith("#"))
.forEach(line -> text.append(line).append('\n'));
}
return text.toString();
}
/** The high-resolution companion of an icon: {@code icon@2x.png} beside {@code icon.png}. */
static Path doubleResolution(Path icon) {
String name = icon.getFileName().toString();
int dot = name.lastIndexOf('.');
return icon.resolveSibling(name.substring(0, dot) + "@2x" + name.substring(dot));
}
}