SshConfigStore.java

/*
 * Copyright (C) 2020, Thomas Wolf <thomas.wolf@paranor.ch> and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0 which is available at
 * https://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
package org.eclipse.jgit.transport;

import java.util.Collections;
import java.util.List;
import java.util.Map;

import org.eclipse.jgit.annotations.NonNull;

/**
 * An abstraction for a SSH config storage, like the OpenSSH ~/.ssh/config file.
 *
 * @since 5.8
 */
public interface SshConfigStore {

    /**
     * Locate the configuration for a specific host request.
     *
     * @param hostName
     *            to look up
     * @param port
     *            the user supplied; &lt;= 0 if none
     * @param userName
     *            the user supplied, may be {@code null} or empty if none given
     * @return the configuration for the requested name.
     */
    @NonNull
    HostConfig lookup(@NonNull String hostName, int port, String userName);

    /**
     * Locate the configuration for a specific host request and if the
     * configuration has no values for {@link SshConstants#HOST_NAME},
     * {@link SshConstants#PORT}, {@link SshConstants#USER}, or
     * {@link SshConstants#CONNECTION_ATTEMPTS}, fill those values with defaults
     * from the arguments:
     * <table>
     * <tr>
     * <th>ssh config key</th>
     * <th>value from argument</th>
     * </tr>
     * <tr>
     * <td>{@code HostName}</td>
     * <td>{@code hostName}</td>
     * </tr>
     * <tr>
     * <td>{@code Port}</td>
     * <td>{@code port > 0 ? port : 22}</td>
     * </tr>
     * <tr>
     * <td>{@code User}</td>
     * <td>{@code userName}</td>
     * </tr>
     * <tr>
     * <td>{@code ConnectionAttempts}</td>
     * <td>{@code 1}</td>
     * </tr>
     * </table>
     *
     * @param hostName
     *            host name to look up
     * @param port
     *            port number; &lt;= 0 if none
     * @param userName
     *            the user name, may be {@code null} or empty if none given
     * @return the configuration for the requested name.
     * @since 6.0
     */
    @NonNull
    HostConfig lookupDefault(@NonNull String hostName, int port,
            String userName);

    /**
     * A host entry from the ssh config. Any merging of global values and of
     * several matching host entries, %-substitutions, and ~ replacement have
     * all been done.
     */
    interface HostConfig {

        /**
         * Retrieves the value of a single-valued key, or the first if the key
         * has multiple values. Keys are case-insensitive, so
         * {@code getValue("HostName") == getValue("HOSTNAME")}.
         *
         * @param key
         *            to get the value of
         * @return the value, or {@code null} if none
         */
        String getValue(String key);

        /**
         * Retrieves the values of a multi- or list-valued key. Keys are
         * case-insensitive, so
         * {@code getValue("HostName") == getValue("HOSTNAME")}.
         *
         * @param key
         *            to get the values of
         * @return a possibly empty list of values
         */
        List<String> getValues(String key);

        /**
         * Retrieves an unmodifiable map of all single-valued options, with
         * case-insensitive lookup by keys.
         *
         * @return all single-valued options
         */
        @NonNull
        Map<String, String> getOptions();

        /**
         * Retrieves an unmodifiable map of all multi- or list-valued options,
         * with case-insensitive lookup by keys.
         *
         * @return all multi-valued options
         */
        @NonNull
        Map<String, List<String>> getMultiValuedOptions();

    }

    /**
     * An empty {@link HostConfig}.
     */
    static final HostConfig EMPTY_CONFIG = new HostConfig() {

        @Override
        public String getValue(String key) {
            return null;
        }

        @Override
        public List<String> getValues(String key) {
            return Collections.emptyList();
        }

        @Override
        public Map<String, String> getOptions() {
            return Collections.emptyMap();
        }

        @Override
        public Map<String, List<String>> getMultiValuedOptions() {
            return Collections.emptyMap();
        }

    };
}