1 /*
2 * Copyright (C) 2020, Thomas Wolf <thomas.wolf@paranor.ch> and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Distribution License v. 1.0 which is available at
6 * https://www.eclipse.org/org/documents/edl-v10.php.
7 *
8 * SPDX-License-Identifier: BSD-3-Clause
9 */
10 package org.eclipse.jgit.transport;
11
12 import java.util.Collections;
13 import java.util.List;
14 import java.util.Map;
15
16 import org.eclipse.jgit.annotations.NonNull;
17
18 /**
19 * An abstraction for a SSH config storage, like the OpenSSH ~/.ssh/config file.
20 *
21 * @since 5.8
22 */
23 public interface SshConfigStore {
24
25 /**
26 * Locate the configuration for a specific host request.
27 *
28 * @param hostName
29 * to look up
30 * @param port
31 * the user supplied; <= 0 if none
32 * @param userName
33 * the user supplied, may be {@code null} or empty if none given
34 * @return the configuration for the requested name.
35 */
36 @NonNull
37 HostConfig lookup(@NonNull String hostName, int port, String userName);
38
39 /**
40 * Locate the configuration for a specific host request and if the
41 * configuration has no values for {@link SshConstants#HOST_NAME},
42 * {@link SshConstants#PORT}, {@link SshConstants#USER}, or
43 * {@link SshConstants#CONNECTION_ATTEMPTS}, fill those values with defaults
44 * from the arguments:
45 * <table>
46 * <tr>
47 * <th>ssh config key</th>
48 * <th>value from argument</th>
49 * </tr>
50 * <tr>
51 * <td>{@code HostName}</td>
52 * <td>{@code hostName}</td>
53 * </tr>
54 * <tr>
55 * <td>{@code Port}</td>
56 * <td>{@code port > 0 ? port : 22}</td>
57 * </tr>
58 * <tr>
59 * <td>{@code User}</td>
60 * <td>{@code userName}</td>
61 * </tr>
62 * <tr>
63 * <td>{@code ConnectionAttempts}</td>
64 * <td>{@code 1}</td>
65 * </tr>
66 * </table>
67 *
68 * @param hostName
69 * host name to look up
70 * @param port
71 * port number; <= 0 if none
72 * @param userName
73 * the user name, may be {@code null} or empty if none given
74 * @return the configuration for the requested name.
75 * @since 6.0
76 */
77 @NonNull
78 HostConfig lookupDefault(@NonNull String hostName, int port,
79 String userName);
80
81 /**
82 * A host entry from the ssh config. Any merging of global values and of
83 * several matching host entries, %-substitutions, and ~ replacement have
84 * all been done.
85 */
86 interface HostConfig {
87
88 /**
89 * Retrieves the value of a single-valued key, or the first if the key
90 * has multiple values. Keys are case-insensitive, so
91 * {@code getValue("HostName") == getValue("HOSTNAME")}.
92 *
93 * @param key
94 * to get the value of
95 * @return the value, or {@code null} if none
96 */
97 String getValue(String key);
98
99 /**
100 * Retrieves the values of a multi- or list-valued key. Keys are
101 * case-insensitive, so
102 * {@code getValue("HostName") == getValue("HOSTNAME")}.
103 *
104 * @param key
105 * to get the values of
106 * @return a possibly empty list of values
107 */
108 List<String> getValues(String key);
109
110 /**
111 * Retrieves an unmodifiable map of all single-valued options, with
112 * case-insensitive lookup by keys.
113 *
114 * @return all single-valued options
115 */
116 @NonNull
117 Map<String, String> getOptions();
118
119 /**
120 * Retrieves an unmodifiable map of all multi- or list-valued options,
121 * with case-insensitive lookup by keys.
122 *
123 * @return all multi-valued options
124 */
125 @NonNull
126 Map<String, List<String>> getMultiValuedOptions();
127
128 }
129
130 /**
131 * An empty {@link HostConfig}.
132 */
133 static final HostConfig EMPTY_CONFIG = new HostConfig() {
134
135 @Override
136 public String getValue(String key) {
137 return null;
138 }
139
140 @Override
141 public List<String> getValues(String key) {
142 return Collections.emptyList();
143 }
144
145 @Override
146 public Map<String, String> getOptions() {
147 return Collections.emptyMap();
148 }
149
150 @Override
151 public Map<String, List<String>> getMultiValuedOptions() {
152 return Collections.emptyMap();
153 }
154
155 };
156 }