Add a series of technical guides to the project

[sugmanue]

Issue #, if available:

Add a series of technical guides to the project

Description of changes:

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[timocov]

Hey @sugmanue, may I ask your/the team vision this method. Currently it is marked as protected and I understand that the main purpose of this is to allow derived "impl" classes to call it, but also in theory it is possible to override it during the codegen to have some extra logic in it (and still call the original method from the base-class):

<I extends SerializableStruct, O extends SerializableStruct> O call(
      I input,
      ApiOperation<I, O> operation,
      RequestOverrideConfig overrideConfig
  ) {
    // some logic here
    return super.call(input, operation, overrideConfig);
  }

If you think that this is a possibility, would it be possible to expose RequestOverrideConfig fields to external consumers (or at least context getter)? Currently every getter in this class is package-private so it is not possible to access them from the outside (e.g. to get the context which was previously set by custom settings set by defaultSettings (similar to

smithy-java/examples/dynamodb-client/smithy-build.json

Lines 9 to 11 in b9d6559

	"defaultSettings": [
	"software.amazon.smithy.java.aws.client.auth.scheme.sigv4.SigV4Settings"
	],

). I understand that the main approach for this type of tasks should be using an interceptor, but when integrating into an existing system it is not always possible and some libraries require to wrap a call so that the context is correctly "scoped". Otherwise it would require either consumers to wrap every client call manually (which is prone to errors) or doing a refactoring on such libraries to allow to "split" their logic into separate phases (how the interceptor works).

Thanks!

[sugmanue]

Hey @timocov, I just saw your comment, can you expand on the some logic here bit. I'd like to better understand the use caas you're envisioning.

The TL;DR is that whatever we make public we will need to support and make sure that we only change in a backwards compatible way which give us less freedom if we want to change anything. So, I'd like to better understand your use case to have some data to make an assessment of the general applicability of it.

[timocov]

@sugmanue for example, lets say you're integrating an XRay-like library into clients so that every client call creates a sub-segment, then the implementation can look something like this:

    <I extends SerializableStruct, O extends SerializableStruct> O call(
        I input,
        ApiOperation<I, O> operation,
        RequestOverrideConfig overrideConfig
    ) {
        // note that "ServiceName.OperationName" can be extracted from operation/service, but I omitted it from this example
        return AWSXRay.getGlobalRecorder().createSegment("ServiceName.OperationName", () -> {
            return super.call(input, operation, overrideConfig);
        });
    }

In this case, we're using library's provided "wrapping" function to make a call so that it can handle "start" and "end" correctly. In case of XRay, it provides beginSegment/endSegment methods so it is not quite fair comparison, but not all libraries have that and if it is a 3rd-party library it might not be even possible.

In my use-case, I have a library that manages current "context" state that then later is being used (or can be used) when making actual http requests at the transport level by adding some headers to request. And unfortunately this library has a couple of features so that even if I introduce begin-end-like methods, it won't be possible as it does some extra logic during this "call"-phase that uses library's internals.