Add README's for most modules.

README.md

@@ -1,26 +1,35 @@
-# <img alt="Smithy" src="https://github.com/smithy-lang/smithy/blob/main/docs/_static/smithy-anvil.svg?raw=true" width="32"> Smithy Java
+# <img alt="Smithy" src="https://github.com/smithy-lang/smithy/blob/main/docs/_static/smithy-anvil.svg?raw=true" width="32"> Smithy Java 
 [![ci](https://github.com/smithy-lang/smithy-java/actions/workflows/ci.yml/badge.svg)](https://github.com/smithy-lang/smithy-java/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
-[Smithy](https://smithy.io/2.0/index.html) code generators for [Java](https://java.com/).
+[Smithy](https://smithy.io/2.0/index.html) code generators for clients, servers, and shapes for [Java](https://java.com/).
 
-> [!Caution]
-> This project is confidential until the repository is made public.
+> [!WARNING]
+> This project is still in development and is not intended for use in production.
 
+## Usage
 > [!WARNING]
-> This project is in early development and is not intended for use in production. 
+> Smithy-Java only supports **Java 17** or later. Older Java versions are not supported.
+
+### API Stability
+APIs annotated with `@SmithyInternal` are for internal use by Smithy-Java libraries and should not be used by Smithy users.
+APIs annotated with `@SmithyUnstableApi` are subject to change in future releases, and library code that other projects
+may depend on should not use these APIs.
 
 ## Development
+See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information on contributing to the Smithy-Java project.
 
 ### Pre-push hooks
-Pre-push hooks are automatically added for unix users via the `addPrePushHooks` gradle task.
+Pre-push hooks are automatically added for unix users via the `addGitHooks` gradle task.
+
 **Note**: In order to successfully execute the pre-defined hooks you must have the `smithy` CLI installed. 
 See [installation instructions](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html) if you do not already have the CLI installed.
 
 ## Security
-
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our 
+[vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). 
+Please do **not** create a public GitHub issue.
 
 ## License
-
 This project is licensed under the Apache-2.0 License.
 

auth-api/README.md

@@ -0,0 +1,2 @@
+## auth-api
+This module provides the auth API for clients and servers.

aws/README.md

@@ -0,0 +1,6 @@
+## AWS SDK Packages
+Packages within this directory are specific to AWS SDKs and the use of AWS services.
+
+### Service Integrations 
+The following integrations for AWS services are provided: 
+- [lambda](./integrations/lambda) - Wrapper for running Smithy Java services on AWS Lambda

aws/client/aws-client-awsjson/README.md

@@ -0,0 +1,3 @@
+## aws-client-awsjson
+Client implementation of the [AWS JSON 1.0](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html#aws-json-1-0-protocol) 
+and [AWS JSON 1.1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocols.

aws/client/aws-client-core/README.md

@@ -0,0 +1,2 @@
+## aws-client-core
+Provides common client functionality for AWS SDKs.

aws/client/aws-client-http/README.md

@@ -0,0 +1,2 @@
+## aws-client-http
+Provides common HTTP functionality for AWS SDKs.

aws/client/aws-client-restjson/README.md

@@ -0,0 +1,3 @@
+## aws-client-restjson
+Client implementation of the [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) 
+protocol.

aws/client/aws-client-restxml/README.md

@@ -0,0 +1,3 @@
+## aws-client-restxml
+Client implementation of the [AWS restXml](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html#aws-restxml-protocol)
+protocol.

aws/server/aws-server-restjson/README.md

@@ -0,0 +1,3 @@
+## aws-server-restjson
+Server implementation of the [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol)
+protocol.

client/client-core/README.md

@@ -0,0 +1,21 @@
+## client-core
+This module provides the core functionality required to execute the client 
+request pipeline. This module is used by both code generated and dynamic clients. 
+
+**Note:** Code generated clients require this module as a runtime dependency.
+
+The functionality provided by this module includes: 
+- Auth Scheme API and Auth Scheme Resolution
+- Identity Resolution
+- Endpoint API and Endpoint Resolution 
+- Client Interceptors
+- Pagination
+- Exception Mapping
+- Client Plugin API 
+- Client Transport API 
+- Client Protocol API
+- Default Client Plugins
+- Base Client settings
+
+To generate a client see the [client-codegen plugin](../codegen/plugins/client).
+To use a dynamic client see the [dynamic-client](../dynamic-client) module.

client/client-core/src/main/java/software/amazon/smithy/java/client/core/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.client.core;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

client/client-http-binding/README.md

@@ -0,0 +1,4 @@
+### client-http-binding
+Provides client specific [http-binding](https://smithy.io/2.0/spec/http-bindings.html#http-bindings) functionality. 
+Http-binding allows Smithy-modeled data to be bound to various parts of an HTTP message such
+as headers, query parameters, or the message body.

client/client-http-binding/src/main/java/software/amazon/smithy/java/client/http/binding/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.client.http.binding;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

client/client-http/README.md

@@ -0,0 +1,2 @@
+### client-http
+Provides a client-side implementation of HTTP transport.

client/client-http/src/main/java/software/amazon/smithy/java/client/http/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.client.http;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

client/client-rpcv2-cbor/README.md

@@ -0,0 +1,41 @@
+## client-rpcv2-cbor
+Client implementation of the [rpcv2-cbor](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#smithy-rpc-v2-cbor-protocol) protocol.
+
+### Usage
+To use this protocol as the default in a generated client, first add the `@rpcv2Cbor` trait
+to your service.
+
+```diff
+$version: "2"
+
+namespace smithy.example
+
++ use smithy.protocols#rpcv2Cbor
+
++@rpcv2Cbor
+service MyService {
+    version: "2020-07-02"
+}
+```
+
+Then add this module as a runtime dependency of your project 
+```diff
+dependencies {
++    implementation("software.amazon.smithy.java:client-rpcv2-cbor")
+}
+```
+
+Finally, configure the client codegen plugin to use this protocol as the
+default 
+```diff
+{
+  "version": "1.0",
+  "plugins": {
+    "java-client-codegen": {
+      "service": "com.example#CoffeeShop",
+      "namespace": "com.example.cafe",
++     "protocol": "smithy.protocols#rpcv2Cbor"
+    }
+  }
+}
+```

client/dynamic-client/README.md

@@ -0,0 +1,34 @@
+### dynamic-client
+Provides a dynamic client that can be used without code generation. 
+
+The dynamic client can load Smithy models at runtime, convert them to a schema-based client, 
+and call a service using `Document` types as input and output. 
+
+### Example usage 
+```java 
+// (1) Load up a model
+var model = Model.assembler()
+    .addImport("/path/to/model.json")
+    .assemble()
+    .unwrap();
+
+// (2) Which service to call
+var shapeId = ShapeId.from("com.example#CoffeeShop");
+
+// (3) make the client and manually wire up the protocol, transport, etc.
+var client = DynamicClient.builder()
+    .service(shapeId)
+    .model(model)
+    .protocol(new RestJsonClientProtocol(shapeId))
+    .transport(new JavaHttpClientTransport())
+    .endpointResolver(EndpointResolver.staticEndpoint("https://api.cafe.example.com"))
+    .build();
+
+// (4) Input is defined using a document that mirrors what you'd see in the Smithy model.
+var input = Document.createFromObject(Map.of("coffeeType", "COLD_BREW"));
+
+// (5) "call" is used to send the input to an operation by name, and it returns a document too.
+var result = client.call("CreateOrder", input).get();
+
+System.out.println(result);
+```

client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.dynamicclient;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

client/mock-client-plugin/README.md

@@ -0,0 +1,38 @@
+## mock-client-plugin
+The MockPlugin is used to intercept client requests and return canned
+responses, shapes, or exceptions. 
+
+### Usage
+```java
+// (1) Create a response queue and add a set of canned responses that will be returned 
+//     from client in the order in which they were added to the queue.
+var mockQueue = new MockQueue();
+mockQueue.enqueue(
+    HttpResponse.builder()
+        .statusCode(200)
+        .body(DataStream.ofString("{\"id\":\"1\"}"))
+    .build()
+);
+mockQueue.enqueue(
+    HttpResponse.builder()
+        .statusCode(429)
+        .body(DataStream.ofString("{\"__type\":\"InvalidSprocketId\"}"))
+    .build()
+);
+
+// (2) Create a MockPlugin instance using the request queue created above.
+var mockPlugin = MockPlugin.builder().addQueue(mockQueue).build();
+
+// (3) Create a client instance that uses the MockPlugin. 
+var client = SprocketClient.builder()
+        .addPlugin(mockPlugin)
+        .build();
+
+// (4) Call client to get the first canned response from the queue.
+var response = client.createSprocket(CreateSprocketRequest.builder().id(2).build());
+
+// (5) Inspect the HTTP requests that were sent to the client.
+var requests = mock.getRequests();
+
+```
+

client/waiters/README.md

@@ -0,0 +1,20 @@
+## waiters
+Provides the core runtime functionality for [Waiters](https://smithy.io/2.0/additional-specs/waiters.html#waiters). 
+
+Waiters are a client-side abstraction used to poll a resource until a desired state is reached, 
+or until it is determined that the resource will never enter into the desired state.
+
+### Usage
+A Waiter can be manually created using:
+```java
+// Create a waiter with a single failure acceptor
+var waiter = Waiter.builder(client::getFoosSync)
+    .failure(Matcher.output(o -> o.status().equals("FAILED")))
+    .build();
+// Wait for up to 2 seconds for waiter to complete
+waiter.wait(input, Duration.ofSeconds(2));
+```
+
+Waiters can also be code generated for your client based on the presence of the `smithy.waiters#waitable` trait.
+To code generate waiters see: [waiter-integration](../../codegen/integrations/waiters-codegen)
+

codecs/cbor-codec/README.md

@@ -0,0 +1,9 @@
+### rpcv2-cbor-codec
+Provides a codec for serializing or deserializing CBOR data to/from
+Smithy-Java `SerializableShape`'s.
+
+> [!NOTE]
+> This codec follows the [Smithy RPCv2 CBOR specification](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#shape-serialization)
+> for the encoding of BigIntegers, BigDecimals, and Timestamps.
+
+CBOR Protocol implementation can use this package to provide basic serde functionality.

codecs/json-codec/README.md

@@ -0,0 +1,8 @@
+## json-codec
+Provides a codec for serializing or deserializing JSON data to/from
+Smithy-Java `SerializableShape`'s.
+
+JSON Protocol implementation can use this package to provide basic serde capabilities.
+
+**Note:** This codec can discover custom `JsonSerdeProvider` service implementations via SPI. 
+By default, [Jackson](https://github.com/FasterXML/jackson) is used to provide JSON serde.

codecs/json-codec/src/main/java/software/amazon/smithy/java/json/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.json;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

codecs/xml-codec/README.md

@@ -0,0 +1,5 @@
+## xml-codec
+Provides a codec for serializing or deserializing XML data to/from 
+Smithy-Java `SerializableShape`'s.
+
+XML Protocol implementation can use this package to provide basic serde.

codegen/core/README.md

@@ -0,0 +1,3 @@
+## codegen-core
+Provides the base functionality for Java code generation used 
+by all Smithy Java codegen plugins.

codegen/integrations/waiters-codegen/README.md

@@ -0,0 +1,16 @@
+## waiters-codegen 
+Codegen integration to generate pre-defined waiters based on
+[waitable](https://smithy.io/2.0/additional-specs/waiters.html#smithy-waiters-waitable-trait) traits in the service model.
+
+### Usage
+```kotlin
+dependencies {
+    // Add codegen integration as a smithy-build dependency, so it can be
+    // discovered by the client codegen plugin
+    smithyBuild("software.amazon.smithy.java.codegen:waiters:<VERSION>")
+
+    // Add waiters core package as a runtime dependency
+    implementation("software.amazon.smithy.java:waiters:<VERSION>")
+}
+```
+

codegen/plugins/client/README.md

@@ -0,0 +1,2 @@
+### codegen-client
+Codegen plugin to generate a Java client from a Smithy model.

codegen/plugins/server/README.md

@@ -0,0 +1,2 @@
+### codegen-server
+Codegen plugin to generate Java server stubs from a Smithy model.

codegen/plugins/types/README.md

@@ -0,0 +1,3 @@
+### codegen-types
+Codegen plugin to generate standalone "plain old Java objects" (POJOs) 
+from a Smithy model.

context/README.md

@@ -0,0 +1,3 @@
+## context
+Provides a typed property map that can be used to store 
+contextual data.

core/README.md

@@ -0,0 +1,3 @@
+## core 
+Provides the core functionality common to all clients and servers 
+using the Smithy Java framework.

framework-errors/README.md

@@ -0,0 +1,5 @@
+## framework-errors
+> [!WARNING]
+> Frameworks errors are a preview feature and may change significantly before 1.0 release.
+
+Provides framework errors common to all Smithy-Java clients and servers.

http-api/README.md

@@ -0,0 +1,2 @@
+## http-api
+Provides the Smithy Java HTTP API.

http-binding/README.md

@@ -0,0 +1,4 @@
+### http-binding
+Provides [http-binding](https://smithy.io/2.0/spec/http-bindings.html#http-bindings) functionality. This allows Smithy-modeled
+data to be bound to various parts of an HTTP message such 
+as headers, query parameters, or the message body.

http-binding/src/main/java/software/amazon/smithy/java/http/binding/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.http.binding;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

io/README.md

@@ -0,0 +1,3 @@
+## io
+Provides the common I/O functionality for Smithy Java such
+as construction and encoding of URL's and handling of data streams.

jmespath/README.md

@@ -0,0 +1,11 @@
+## jmespath
+Provides functionality to perform a [JMESPath](https://jmespath.org/) query 
+against a Smithy-Java `Document`.
+
+### Example Usage
+Given a `Document` representing the JSON object `{"foo": [1,2,3,4]}`,
+all items in member `foo` greater than 2 could be queried as:
+
+```java 
+Document result = JMESPathDocumentQuery.query("foo[?@ > `2`]", myDocument);
+```

jmespath/src/main/java/software/amazon/smithy/java/jmespath/package-info.java

@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.jmespath;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;

logging/README.md

@@ -0,0 +1,11 @@
+## logging
+> [!WARNING]
+> This module is intended for internal components of the Smithy Java framework
+> and should not be depended on by projects outside of this repository.
+
+This package provides a common logging facade for internal 
+Smithy-Java logging. This logging facade supports the following 
+logger implementations: 
+- JDK System Logger (default)
+- Log4j2 Logger
+- Slf4j2 Logger