forked from smithy-lang/smithy-typescript
-
Notifications
You must be signed in to change notification settings - Fork 0
/
TypeScriptSettings.java
568 lines (502 loc) · 21.2 KB
/
TypeScriptSettings.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file 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 software.amazon.smithy.typescript.codegen;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
import java.util.Set;
import java.util.function.BiFunction;
import java.util.logging.Logger;
import java.util.stream.Collectors;
import software.amazon.smithy.codegen.core.CodegenException;
import software.amazon.smithy.codegen.core.SymbolProvider;
import software.amazon.smithy.model.Model;
import software.amazon.smithy.model.knowledge.ServiceIndex;
import software.amazon.smithy.model.node.BooleanNode;
import software.amazon.smithy.model.node.Node;
import software.amazon.smithy.model.node.ObjectNode;
import software.amazon.smithy.model.node.StringNode;
import software.amazon.smithy.model.shapes.ServiceShape;
import software.amazon.smithy.model.shapes.Shape;
import software.amazon.smithy.model.shapes.ShapeId;
import software.amazon.smithy.model.traits.DefaultTrait;
import software.amazon.smithy.model.traits.RequiredTrait;
import software.amazon.smithy.utils.SmithyUnstableApi;
/**
* Settings used by {@link TypeScriptCodegenPlugin}.
*/
@SmithyUnstableApi
public final class TypeScriptSettings {
static final String DISABLE_DEFAULT_VALIDATION = "disableDefaultValidation";
static final String REQUIRED_MEMBER_MODE = "requiredMemberMode";
private static final Logger LOGGER = Logger.getLogger(TypeScriptSettings.class.getName());
private static final String PACKAGE = "package";
private static final String PACKAGE_DESCRIPTION = "packageDescription";
private static final String PACKAGE_VERSION = "packageVersion";
private static final String PACKAGE_JSON = "packageJson";
private static final String SERVICE = "service";
private static final String PROTOCOL = "protocol";
private static final String PRIVATE = "private";
private static final String PACKAGE_MANAGER = "packageManager";
private static final String CREATE_DEFAULT_README = "createDefaultReadme";
private static final String EXPERIMENTAL_IDENTITY_AND_AUTH = "experimentalIdentityAndAuth";
private String packageName;
private String packageDescription = "";
private String packageVersion;
private ObjectNode packageJson = Node.objectNode();
private ShapeId service;
private ObjectNode pluginSettings = Node.objectNode();
private ShapeId protocol;
private String defaultSigningName = "";
private boolean isPrivate;
private ArtifactType artifactType = ArtifactType.CLIENT;
private boolean disableDefaultValidation = false;
private RequiredMemberMode requiredMemberMode =
RequiredMemberMode.NULLABLE;
private PackageManager packageManager = PackageManager.YARN;
private boolean createDefaultReadme = false;
private boolean experimentalIdentityAndAuth = false;
@Deprecated
public static TypeScriptSettings from(Model model, ObjectNode config) {
return from(model, config, ArtifactType.CLIENT);
}
/**
* Create a settings object from a configuration object node.
*
* @param model Model to infer the service to generate if not explicitly provided.
* @param config Config object to load.
* @param artifactType The type of artifact being generated.
* @return Returns the extracted settings.
*/
public static TypeScriptSettings from(Model model, ObjectNode config, ArtifactType artifactType) {
TypeScriptSettings settings = new TypeScriptSettings();
settings.setArtifactType(artifactType);
config.warnIfAdditionalProperties(artifactType.configProperties);
// Get the service from the settings or infer one from the given model.
settings.setService(config.getStringMember(SERVICE)
.map(StringNode::expectShapeId)
.orElseGet(() -> inferService(model)));
settings.setPackageName(config.expectStringMember(PACKAGE).getValue());
settings.setPackageVersion(config.expectStringMember(PACKAGE_VERSION).getValue());
settings.setPackageDescription(config.getStringMemberOrDefault(
PACKAGE_DESCRIPTION, settings.getDefaultDescription()));
settings.packageJson = config.getObjectMember(PACKAGE_JSON).orElse(Node.objectNode());
config.getStringMember(PROTOCOL).map(StringNode::getValue).map(ShapeId::from).ifPresent(settings::setProtocol);
settings.setPrivate(config.getBooleanMember(PRIVATE).map(BooleanNode::getValue).orElse(false));
settings.setCreateDefaultReadme(
config.getBooleanMember(CREATE_DEFAULT_README).map(BooleanNode::getValue).orElse(false));
settings.setExperimentalIdentityAndAuth(
config.getBooleanMemberOrDefault(EXPERIMENTAL_IDENTITY_AND_AUTH, false));
settings.setPackageManager(
config.getStringMember(PACKAGE_MANAGER)
.map(s -> PackageManager.fromString(s.getValue()))
.orElse(PackageManager.YARN));
if (artifactType == ArtifactType.SSDK) {
settings.setDisableDefaultValidation(config.getBooleanMemberOrDefault(DISABLE_DEFAULT_VALIDATION));
}
settings.setRequiredMemberMode(
config.getStringMember(REQUIRED_MEMBER_MODE)
.map(s -> RequiredMemberMode.fromString(s.getValue()))
.orElse(RequiredMemberMode.NULLABLE));
settings.setPluginSettings(config);
return settings;
}
private String getDefaultDescription() {
String description = getPackageName();
switch (artifactType) {
case CLIENT:
description += " client";
break;
case SSDK:
description += " server";
break;
default:
}
return description;
}
// TODO: this seems reusable across generators.
private static ShapeId inferService(Model model) {
List<ShapeId> services = model
.shapes(ServiceShape.class)
.map(Shape::getId)
.sorted()
.collect(Collectors.toList());
if (services.isEmpty()) {
throw new CodegenException("Cannot infer a service to generate because the model does not "
+ "contain any service shapes");
} else if (services.size() > 1) {
throw new CodegenException("Cannot infer a service to generate because the model contains "
+ "multiple service shapes: " + services);
} else {
LOGGER.info("Inferring service to generate as " + services.get(0));
return services.get(0);
}
}
/**
* Gets the required package name that is going to be generated.
*
* @return Returns the package name.
* @throws NullPointerException if the service has not been set.
*/
public String getPackageName() {
return Objects.requireNonNull(packageName, PACKAGE + " not set");
}
public void setPackageName(String packageName) {
this.packageName = packageName;
}
/**
* Gets the description of the package that will be placed in the
* "description" field of the generated package.json.
*
* @return Returns the description or an empty string if not set.
*/
public String getPackageDescription() {
return packageDescription;
}
public void setPackageDescription(String packageDescription) {
this.packageDescription = Objects.requireNonNull(packageDescription);
}
/**
* Gets the version of the generated package that will be used with the
* generated package.json file.
*
* @return Returns the package version.
*/
public String getPackageVersion() {
return packageVersion;
}
public void setPackageVersion(String packageVersion) {
this.packageVersion = packageVersion;
}
/**
* Gets a chunk of custom properties to merge into the generated
* package.json file.
*
* <p>This JSON is used to provide any property present in the
* package.json file that isn't captured by any other settings.
* This value will never be {@code null}.
*
* @return Returns the custom package JSON.
*/
public ObjectNode getPackageJson() {
return packageJson;
}
/**
* Sets the custom package.json properties.
*
* @param packageJson package.json properties to merge in.
*/
public void setPackageJson(ObjectNode packageJson) {
this.packageJson = Objects.requireNonNull(packageJson);
}
/**
* Gets the optional name of the service that is being generated.
*
* @return Returns the package name.
* @throws NullPointerException if the service has not been set.
*/
public ShapeId getService() {
return Objects.requireNonNull(service, SERVICE + " not set");
}
public void setService(ShapeId service) {
this.service = Objects.requireNonNull(service);
}
/**
* Gets additional plugin settings.
*
* <p>This value will never throw or return {@code null}.
*
* @return Returns the entire settings object.
*/
public ObjectNode getPluginSettings() {
return pluginSettings;
}
public void setPluginSettings(ObjectNode pluginSettings) {
this.pluginSettings = Objects.requireNonNull(pluginSettings);
}
/**
* Returns if the generated package will be made private.
*
* @return If the package will be private.
*/
public boolean isPrivate() {
return isPrivate;
}
public void setPrivate(boolean isPrivate) {
this.isPrivate = isPrivate;
}
public boolean createDefaultReadme() {
return createDefaultReadme;
}
public void setCreateDefaultReadme(boolean createDefaultReadme) {
this.createDefaultReadme = createDefaultReadme;
}
/**
* Returns if the generated package will be a client.
*
* @return If the package will include a client.
*/
public boolean generateClient() {
return artifactType.equals(ArtifactType.CLIENT);
}
/**
* Returns if the generated package will be a server sdk.
*
* @return If the package will include a server sdk.
*/
public boolean generateServerSdk() {
return artifactType.equals(ArtifactType.SSDK);
}
/**
* Returns the type of artifact being generated, such as a client or ssdk.
*
* @return The artifact type.
*/
public ArtifactType getArtifactType() {
return artifactType;
}
public void setArtifactType(ArtifactType artifactType) {
this.artifactType = artifactType;
}
/**
* Returns whether or not default validation is disabled. This setting is only relevant for the SSDK.
*
* @return true if default validation is disabled. Default: false
*/
public boolean isDisableDefaultValidation() {
return disableDefaultValidation;
}
public void setDisableDefaultValidation(boolean disableDefaultValidation) {
this.disableDefaultValidation = disableDefaultValidation;
}
/**
* Returns the code generation mode for required members.
*
* @return the configured mode for required members.
* Defaults to {@link RequiredMemberMode#NULLABLE}
*/
public RequiredMemberMode getRequiredMemberMode() {
return requiredMemberMode;
}
public void setRequiredMemberMode(
RequiredMemberMode requiredMemberMode) {
if (requiredMemberMode != RequiredMemberMode.NULLABLE) {
LOGGER.warning(String.format("By setting the required member mode to '%s', a"
+ " member that has the '@required' trait applied CANNOT be 'undefined'."
+ " It will be considered a BACKWARDS INCOMPATIBLE change for"
+ " Smithy services even when the required constraint is dropped from a member.",
requiredMemberMode.mode, RequiredMemberMode.NULLABLE.mode));
}
this.requiredMemberMode = requiredMemberMode;
}
/**
* Returns the package manager used by the generated package.
*
* @return the configured package manager. Defaults to {@link PackageManager#YARN}
*/
public PackageManager getPackageManager() {
return packageManager;
}
public void setPackageManager(PackageManager packageManager) {
this.packageManager = packageManager;
}
/**
* Returns whether to use experimental identity and auth.
*
* @return if experimental identity and auth should used. Default: false
*/
public boolean getExperimentalIdentityAndAuth() {
return experimentalIdentityAndAuth;
}
/**
* Sets whether experimental identity and auth should be used.
*
* @param experimentalIdentityAndAuth whether experimental identity and auth should be used.
*/
public void setExperimentalIdentityAndAuth(boolean experimentalIdentityAndAuth) {
if (experimentalIdentityAndAuth) {
LOGGER.warning("""
Experimental identity and auth is in development, and is subject to \
breaking changes. Behavior may NOT have the same feature parity as \
non-experimental behavior. This setting is also subject to removal \
when the feature is completed.""");
}
this.experimentalIdentityAndAuth = experimentalIdentityAndAuth;
}
/**
* Gets the corresponding {@link ServiceShape} from a model.
*
* @param model Model to search for the service shape by ID.
* @return Returns the found {@code Service}.
* @throws NullPointerException if the service has not been set.
* @throws CodegenException if the service is invalid or not found.
*/
public ServiceShape getService(Model model) {
return model
.getShape(getService())
.orElseThrow(() -> new CodegenException("Service shape not found: " + getService()))
.asServiceShape()
.orElseThrow(() -> new CodegenException("Shape is not a Service: " + getService()));
}
/**
* Gets the configured protocol to generate.
*
* @return Returns the configured protocol.
*/
public ShapeId getProtocol() {
return protocol;
}
/**
* Resolves the highest priority protocol from a service shape that is
* supported by the generator.
*
* @param model Model to enable finding protocols on the service.
* @param service Service to get the protocols from if "protocols" is not set.
* @param supportedProtocols The set of protocol names supported by the generator.
* @return Returns the resolved protocol name.
* @throws UnresolvableProtocolException if no protocol could be resolved.
*/
public ShapeId resolveServiceProtocol(Model model, ServiceShape service, Set<ShapeId> supportedProtocols) {
if (protocol != null) {
return protocol;
}
ServiceIndex serviceIndex = ServiceIndex.of(model);
Set<ShapeId> resolvedProtocols = serviceIndex.getProtocols(service).keySet();
if (resolvedProtocols.isEmpty()) {
throw new UnresolvableProtocolException(
"Unable to derive the protocol setting of the service `" + service.getId() + "` because no "
+ "protocol definition traits were present. You need to set an explicit `protocol` to "
+ "generate in smithy-build.json to generate this service.");
}
return resolvedProtocols.stream()
.filter(supportedProtocols::contains)
.findFirst()
.orElseThrow(() -> new UnresolvableProtocolException(String.format(
"The %s service supports the following unsupported protocols %s. The following protocol "
+ "generators were found on the class path: %s",
service.getId(), resolvedProtocols, supportedProtocols)));
}
/**
* Sets the protocol to generate.
*
* @param protocol Protocols to generate.
*/
public void setProtocol(ShapeId protocol) {
this.protocol = Objects.requireNonNull(protocol);
}
/**
* @param name - used as the signing service name when no explicit value from endpoints AuthScheme is present.
*/
public void setDefaultSigningName(String name) {
defaultSigningName = name;
}
/**
* @return signing service name when no explicit value from endpoints AuthScheme is present.
*/
public String getDefaultSigningName() {
return defaultSigningName;
}
/**
* An enum indicating the type of artifact the code generator will produce.
*/
public enum ArtifactType {
CLIENT(SymbolVisitor::new,
Arrays.asList(PACKAGE, PACKAGE_DESCRIPTION, PACKAGE_JSON, PACKAGE_VERSION, PACKAGE_MANAGER,
SERVICE, PROTOCOL, PRIVATE, REQUIRED_MEMBER_MODE,
CREATE_DEFAULT_README, EXPERIMENTAL_IDENTITY_AND_AUTH)),
SSDK((m, s) -> new ServerSymbolVisitor(m, new SymbolVisitor(m, s)),
Arrays.asList(PACKAGE, PACKAGE_DESCRIPTION, PACKAGE_JSON, PACKAGE_VERSION, PACKAGE_MANAGER,
SERVICE, PROTOCOL, PRIVATE, REQUIRED_MEMBER_MODE,
DISABLE_DEFAULT_VALIDATION, CREATE_DEFAULT_README));
private final BiFunction<Model, TypeScriptSettings, SymbolProvider> symbolProviderFactory;
private final List<String> configProperties;
ArtifactType(BiFunction<Model, TypeScriptSettings, SymbolProvider> symbolProviderFactory,
List<String> configProperties) {
this.symbolProviderFactory = symbolProviderFactory;
this.configProperties = Collections.unmodifiableList(configProperties);
}
/**
* Creates a TypeScript symbol provider suited to the artifact type.
*
* @param model Model to generate symbols for.
* @param settings Settings used by the symbol provider.
* @return Returns the created provider.
*/
public SymbolProvider createSymbolProvider(Model model, TypeScriptSettings settings) {
return symbolProviderFactory.apply(model, settings);
}
}
/**
* An enum indicating the code generation mode for required members.
*/
public enum RequiredMemberMode {
/**
* This is the current behavior and it will be the default. When set,
* it allows a member that has the {@link RequiredTrait} applied to be {@code undefined}.
* By doing so it can still be considered a backwards compatible change fo
* Smithy services even when the required constraint is dropped from a member.
*/
NULLABLE("nullable"),
/**
* This will dissallow members marked as {@link RequiredTrait} to be {@code undefined}.
* Use this mode with CAUTION because it comes with certain risks. When a server drops
* {@link RequiredTrait} from an output shape (and it is replaced with {@link DefaultTrait}
* as defined by the spec), if the server does not always serialize a value,
* customer code consuming the client and trying to access this member, may get a
* NullPointerException. Smithy spec says: "Authoritative model consumers like servers
* SHOULD always serialize default values to remove any ambiguity about the value of
* the most up to default value." So one should use this mode on the client, only if
* the server is following the approach proposed by the spec.
*/
STRICT("strict");
private final String mode;
RequiredMemberMode(String mode) {
this.mode = mode;
}
public String getMode() {
return mode;
}
public static RequiredMemberMode fromString(String s) {
if ("nullable".equals(s)) {
return NULLABLE;
}
if ("strict".equals(s)) {
return STRICT;
}
throw new CodegenException(String.format("Unsupported required member mode: %s", s));
}
}
public enum PackageManager {
YARN("yarn"),
NPM("npm");
private final String command;
PackageManager(String command) {
this.command = command;
}
public String getCommand() {
return command;
}
public static PackageManager fromString(String s) {
if ("yarn".equals(s)) {
return YARN;
}
if ("npm".equals(s)) {
return NPM;
}
throw new CodegenException(String.format("Unsupported package manager: %s", s));
}
}
}