1 package com.guinetik.rr;
2
3 import com.guinetik.rr.auth.AuthStrategy;
4 import com.guinetik.rr.auth.RocketSSL;
5
6 import java.util.function.Consumer;
7
8 /**
9 * Extended configuration for {@link RocketRest} clients requiring custom SSL/TLS certificates.
10 *
11 * <p>This class extends {@link RocketRestConfig} to provide support for custom SSL certificates,
12 * enabling secure connections to APIs that use self-signed certificates, custom certificate
13 * authorities, or require mutual TLS (mTLS) authentication.
14 *
15 * <h2>When to Use</h2>
16 * <ul>
17 * <li>Connecting to APIs with self-signed SSL certificates</li>
18 * <li>Corporate environments with internal certificate authorities</li>
19 * <li>Mutual TLS (mTLS) authentication requirements</li>
20 * <li>Development/staging environments with non-production certificates</li>
21 * </ul>
22 *
23 * <h2>Basic Usage</h2>
24 * <pre class="language-java"><code>
25 * RocketRestSecureConfig config = RocketRestSecureConfig
26 * .secureBuilder("https://secure-api.internal.corp")
27 * .withCustomCertificate("/path/to/keystore.p12", "keystorePassword")
28 * .authStrategy(AuthStrategyFactory.createBearerToken("api-token"))
29 * .build();
30 *
31 * RocketRest client = new RocketRest(config);
32 * SecureData data = client.get("/secure/data", SecureData.class);
33 * </code></pre>
34 *
35 * <h2>With OAuth2 and Custom Certificate</h2>
36 * <pre class="language-java"><code>
37 * RocketRestSecureConfig config = RocketRestSecureConfig
38 * .secureBuilder("https://api.internal.corp")
39 * .withCustomCertificate("client-cert.p12", "certPassword")
40 * .authStrategy(AuthStrategyFactory.createOAuth2ClientCredentials(
41 * "client-id",
42 * "client-secret",
43 * "https://auth.internal.corp/oauth/token"
44 * ))
45 * .tokenUrl("https://auth.internal.corp/oauth/token")
46 * .defaultOptions(opts -> {
47 * opts.set(RocketRestOptions.RETRY_ENABLED, true);
48 * opts.set(RocketRestOptions.MAX_RETRIES, 3);
49 * })
50 * .build();
51 *
52 * RocketRest client = new RocketRest(config);
53 * </code></pre>
54 *
55 * @author guinetik <guinetik@gmail.com>
56 * @see RocketRestConfig
57 * @see RocketSSL
58 * @see RocketRest
59 * @since 1.0.0
60 */
61 public class RocketRestSecureConfig extends RocketRestConfig implements RocketSSL.SSLConfig {
62 /**
63 * Builder for creating RocketRestSecureConfig instances.
64 */
65 public static class SecureBuilder extends RocketRestConfig.Builder {
66 private boolean customCertificateEnabled;
67 private String customCertificateFilename;
68 private String customCertificatePassword;
69
70 protected SecureBuilder(String serviceUrl) {
71 super(serviceUrl);
72 }
73
74 /**
75 * Enables a custom SSL certificate with the given filename and password.
76 *
77 * @param filename the custom certificate filename
78 * @param password the custom certificate password
79 * @return this builder instance
80 */
81 public SecureBuilder withCustomCertificate(String filename, String password) {
82 this.customCertificateEnabled = true;
83 this.customCertificateFilename = filename;
84 this.customCertificatePassword = password;
85 return this;
86 }
87
88 @Override
89 public SecureBuilder tokenUrl(String tokenUrl) {
90 super.tokenUrl(tokenUrl);
91 return this;
92 }
93
94 @Override
95 public SecureBuilder authStrategy(AuthStrategy authStrategy) {
96 super.authStrategy(authStrategy);
97 return this;
98 }
99
100 @Override
101 public SecureBuilder defaultOptions(Consumer<RocketRestOptions> optionsConfigurer) {
102 super.defaultOptions(optionsConfigurer);
103 return this;
104 }
105
106 @Override
107 public SecureBuilder defaultOption(String key, Object value) {
108 super.defaultOption(key, value);
109 return this;
110 }
111
112 /**
113 * Builds a new RocketRestSecureConfig instance.
114 *
115 * @return a new RocketRestSecureConfig instance
116 */
117 @Override
118 public RocketRestSecureConfig build() {
119 return new RocketRestSecureConfig(this);
120 }
121 }
122 // Certificate options
123 private final boolean customCertificateEnabled;
124 private final String customCertificateFilename;
125 private final String customCertificatePassword;
126
127 // Package-private constructor for access by SecureBuilder
128 protected RocketRestSecureConfig(SecureBuilder builder) {
129 // Use the protected constructor from a parent
130 super(builder);
131 this.customCertificateEnabled = builder.customCertificateEnabled;
132 this.customCertificateFilename = builder.customCertificateFilename;
133 this.customCertificatePassword = builder.customCertificatePassword;
134 }
135
136 /**
137 * Checks if a custom SSL certificate is enabled.
138 *
139 * @return true if a custom certificate is enabled
140 */
141 public boolean isCustomCertificateEnabled() {
142 return customCertificateEnabled;
143 }
144
145 /**
146 * Gets the custom certificate filename.
147 *
148 * @return the custom certificate filename
149 */
150 public String getCustomCertificateFilename() {
151 return customCertificateFilename;
152 }
153
154 /**
155 * Gets the custom certificate password.
156 *
157 * @return the custom certificate password
158 */
159 public String getCustomCertificatePassword() {
160 return customCertificatePassword;
161 }
162
163 /**
164 * Creates a new secure builder for RocketRestConfig.
165 *
166 * @param serviceUrl the base URL for the API service
167 * @return a new secure builder instance
168 */
169 public static SecureBuilder secureBuilder(String serviceUrl) {
170 return new SecureBuilder(serviceUrl);
171 }
172 }