BlobIndex.java

package network.ike.docs.plugin.registry;

import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;

/**
 * Every {@code .adoc} file under a registry root with the git blob id of its
 * content: the key the incremental registry decides staleness by
 * ({@code dev-adoc-packages}, IKE-Network/ike-issues#1341). Dates are the
 * wrong key, since a checkout, a rebase, a sync between machines or a
 * restored file all change dates without changing content; the blob id
 * addresses the content itself, and git already keeps it for every tracked
 * file. {@link GitBlobIndex} reads it from git without opening a file;
 * {@link #hashed(Path)} is the fallback for a tree without git, which
 * reads every file once to compute the same id, so the two never disagree
 * about an unchanged file.
 *
 * <p>Paths are relative to the root with {@code /} separators, in path
 * order, with the directories {@link TopicRegistry#SKIPPED_DIRS} left out,
 * as the full scan leaves them out. A symbolic link is never followed; it
 * is a finding instead, as it is in the full scan.
 *
 * @param blobs    the files, path to blob id, iterating in path order
 * @param findings what the index could not take: a symbolic link, prefixed
 *                 with the path it concerns
 * @param source   where the ids came from
 * @since 136
 */
public record BlobIndex(Map<String, String> blobs, List<String> findings, Source source) {

    /** Where a {@link BlobIndex} took its blob ids from. */
    public enum Source {
        /** From {@code git ls-files}, {@code git status} and {@code git hash-object}. */
        GIT,
        /** Computed in Java by reading every file: the tree has no git. */
        HASHED
    }

    /**
     * Index a root by reading every {@code .adoc} file under it and hashing
     * the content as git hashes a blob ({@code "blob " + length + NUL +
     * content}, SHA-1). This is the full scan's cost, paid when git is not
     * there to answer for free.
     *
     * @param root the registry root
     * @return the index
     * @throws IOException if the tree cannot be read
     */
    public static BlobIndex hashed(Path root) throws IOException {
        Path real = root.toRealPath();
        Map<String, String> blobs = new TreeMap<>();
        List<String> findings = new ArrayList<>();
        Files.walkFileTree(real, new SimpleFileVisitor<>() {
            @Override
            public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
                if (!dir.equals(real) && TopicRegistry.SKIPPED_DIRS.contains(dir.getFileName().toString())) {
                    return FileVisitResult.SKIP_SUBTREE;
                }
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
                if (!file.getFileName().toString().endsWith(".adoc")) {
                    return FileVisitResult.CONTINUE;
                }
                String relative = real.relativize(file).toString().replace('\\', '/');
                if (attrs.isSymbolicLink()) {
                    findings.add(relative + ": symbolic link, skipped");
                } else if (attrs.isRegularFile()) {
                    try {
                        blobs.put(relative, blobId(Files.readAllBytes(file)));
                    } catch (IOException e) {
                        throw new UncheckedIOException(e);
                    }
                }
                return FileVisitResult.CONTINUE;
            }
        });
        findings.sort(null);
        return new BlobIndex(Collections.unmodifiableMap(blobs), List.copyOf(findings), Source.HASHED);
    }

    /**
     * The git blob id of content: the SHA-1 of {@code "blob <length>\0"}
     * followed by the bytes, as {@code git hash-object} computes it for a
     * file with no clean filter.
     *
     * @param content the file content
     * @return the forty-character lowercase hex id
     */
    public static String blobId(byte[] content) {
        try {
            MessageDigest sha1 = MessageDigest.getInstance("SHA-1");
            sha1.update(("blob " + content.length + "\0").getBytes(StandardCharsets.US_ASCII));
            byte[] digest = sha1.digest(content);
            StringBuilder hex = new StringBuilder(40);
            for (byte b : digest) {
                hex.append(Character.forDigit((b >> 4) & 0xf, 16)).append(Character.forDigit(b & 0xf, 16));
            }
            return hex.toString();
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException("SHA-1 is not available", e);
        }
    }

    /**
     * Whether a relative path lies under a directory the scan never enters.
     *
     * @param relative a path relative to the root with {@code /} separators
     * @return true when some directory of the path is in {@link TopicRegistry#SKIPPED_DIRS}
     */
    static boolean skipped(String relative) {
        int from = 0;
        int slash;
        while ((slash = relative.indexOf('/', from)) >= 0) {
            if (TopicRegistry.SKIPPED_DIRS.contains(relative.substring(from, slash))) {
                return true;
            }
            from = slash + 1;
        }
        return false;
    }
}