Tomodachi

- Updated version constraints of the `opentelemetry-exporter-prometheus` dependency to use the correct (non-yanked) version range.
- Support for `aiobotocore` 2.8.x releases and 2.9.x releases.

- Support for Python 3.12. Python 3.12 has been added to test matrix and trove classifiers.
- Supports `aiohttp` 3.9.x versions.
- Updated OpenTelemetry distro to handle MetricReaders and MetricExporters in a more flexible way (similar to how it was changed to be done in `opentelemetry-sdk` 1.21.0).
- Log entries from `tomodachi.logging` on OTEL instrumented services will now include TraceContext (`span_id`, `trace_id` and `parent_span_id`) on non-recording (but valid) spans.

- Uses less strict version constraints on OpenTelemetry dependencies to make it easier to use newer versions of OpenTelemetry libraries together with `tomodachi` services.
- Passes FIFO message attributes (`message_deduplication_id` and `message_group_id`) to `tomodachi` handler functions as keyword argument provided transport values. (github: **filipsnastins**)

**New and updated**

- Major refactoring of how logging is done, introducing `tomodachi.get_logger()` built on `structlog`. Contextual logger available for all handlers, etc.
- Provides the option of hooking in `tomodachi` to a custom logger the user provides.
- Adds instrumentation for `opentelemetry` (OTEL / OpenTelemetry) that can be enabled if `tomodachi` is installed using the `opentelemetry` extras.
- OTEL auto instrumentation can be achieved by starting services using either the `tomodachi run` argument `--opentelemetry-instrument` (equivalent to setting env: `TOMODACHI_OPENTELEMETRY_INSTRUMENT=1`) or using the `opentelemetry-instrument` CLI.
- An experimental meter provider for exporting OpenTelemetry metrics on a Prometheus server can be used by installing the `opentelemetry-exporter-prometheus` extras and using the `OTEL_PYTHON_METER_PROVIDER=tomodachi_prometheus` environment value in combination with OTEL instrumentation.
- Adds the option to enable exemplars in the Prometheus client for OpenTelemetry metrics, to be able to link to traces from collected metrics in Grafana, et al.
- The HTTP body for requests with a body is read before the handler is called and if the connection was closed prematurely before the body could be read, the request will be ignored.
- Replaces the banner shown when starting a service without `--production`. The banner now includes the operating system, architecture, which Python runtime from which virtualenv is used, etc. in order to aid debugging during development for issues caused by environment misconfiguration.
- Updated the CLI usage output from `--help`.
- Added a value `tomodachi.__build_time__` which includes the timestamp when the build for the installed release was done. The time that has passed since build time will be included in the start banner.
- Makes use of `asyncio` tasks instead of simply awaiting the coroutines so that the context from contextvars will be propagated correctly and not risk being corrupted by handlers.
- Added an internal lazy meta importer to ease renaming and deprecations of modules.
- Added additional lazy loading of submodules.
- Each argument for `tomodachi run` is now accompanied with an environment variable to do the same. For example `--log-level warning` can be achieved by setting `TOMODACHI_LOG_LEVEL=warning`.
- Updated documentation with additional information.

**Potentially breaking changes**

- The complete refactoring of logging changes how log entries are being emitted, both in the way that the event / message of the log records has changed, but also how a log handler is now also added to the `logging.root` logger on service start.
- Third party log records will if propagation is enabled also be processed in `tomodachi.logging` which may cause duplicate log output depending on how the third party logger is configured.
- Removed the `log_setup()` function that previously was added to the service object on class initialization and that was used to setup log output to disk.
- Tracebacks for uncaught exceptions are now extracted to only include frames relevant to the service application and not the internal `tomodachi` frames, which usually will be uninteresting for debugging.

**Bug fixes**

- Fixes exception catching of lifecycle handlers (`_start_service`, `_started_service`, etc.) which previously could stall a service raising an exception while starting, instead of exiting with a non-zero exit code.
- Bug fix for an issue which could cause the watcher to fail to restart the service after a syntax error was encountered.
- Adds some missing type hint annotations.
- Added additional logging of uncaught exceptions that previously may have been silenced.
- Fixed that the `--log-level` CLI argument value is actually applied to loggers.
- Fix for a race condition which could freeze a process if a service was manually stopped (interrupted with ctrl+c) before it had called its first lifecycle function (`_start_service`).

**Deprecations**

- Added deprecation warnings for more legacy functionality to give notice that those functions will be removed in a future release.
- The use of the `log()` function added to the service object is deprecated. Use the `structlog` logger from `tomodachi.get_logger()` instead.
- Using the `RequestHandler.get_request_ip` is deprecated. Instead use the `tomodachi.get_forwarded_remote_ip()` function.
- Deprecated the use of the CLI argument `-c` (`--config`) which could be used to set object attributes from a JSON file. A better pattern is to read optional config data from an environment variable.

- Fix for an issue where a wrapped function is used as a handler function, which would then cause the keyword argument provided transport values to rely on the keyword arguments from the *wrapped function's* signature to be used instead of the keyword arguments from the *wrapper function's* signature.

The bug was found to be present since the last release, which included major refactoring of the *keyword argument provided transport values* functionality.

- The middleware execution logic has been improved to handle different argument types and edge cases more smoothly. Enhanced the way arguments are passed to middlewares and handlers, allowing better flexibility.

- Resolved an edge case where a service could end up calling `SNS.CreateTopic` numerous times due to thousands of messages simultanously being published to a topic that were previously unknown to the service.

- The `aws_sns_sqs_publish` function will now return the SNS message identifier as a `str` value if it is called with `wait=True` (default), or instead return an `asyncio.Task` object if called with `wait=False`.

- Function handlers, middlewares and envelopes can all now specify additional keyword arguments in their signatures and receive transport centric values.

Previously a few of these keyword values could be used for function handlers or envelopes, but not within middlewares. With this update the following keywords can be used across all kind of handler functions to allow for more flexibility in how to structure apps, logging, tracing, authentication, etc.

**Category: AWS SNS+SQS related values**

Use the following keywords arguments in function signatures (for handlers, middlewares and envelopes used for AWS SNS+SQS messages).

| | |
|:---|:---|
| `message_attributes` | Values specified as message attributes that accompanies the message body and that are among other things used for SNS queue subscription filter policies and for distributed tracing.
| `queue_url` | Can be used to modify visibility of messages, provide exponential backoffs, move to DLQs, etc.
| `receipt_handle` | Can be used to modify visibility of messages, provide exponential backoffs, move to DLQs, etc.
| `approximate_receive_count` | A value that specifies approximately how many times this message has been received from consumers on `SQS.ReceiveMessage` calls. Handlers that received a message, but that doesn't delete it from the queue (for example in order to make it visible for other consumers or in case of errors), will add to this count for each time they received it.
| `topic` | Simply the name of the SNS topic. For messages sent directly to the queue (for example via `SQS.SendMessage` API calls), instead of via SNS topic subscriptions (`SNS.Publish`), the value of `topic` will be an empty string.
| `sns_message_id` | The message identifier for the SNS message (which is usually embedded in the body of a SQS message). Ths SNS message identifier is the same that is returned in the response when publishing a message with `SNS.Publish`. The `sns_message_id` is read from within the `"Body"` of SQS messages, if the message body contains a message that comes from an SNS topic subscription.
| `sqs_message_id` | The SQS message identifier, which naturally will differ from the SNS message identifier as one SNS message can be propagated to several SQS queues. The `sqs_message_id` is read from the `"MessageId"` value in the top of the SQS message.
| `message_timestamp` | A timestamp of when the original SNS message was published.

**Category: "HTTP related values"**

Use the following keywords arguments in function signatures (for handlers and middlewares used for HTTP requests).

| | |
|:---|:---|
| `request` | The `aiohttp` request object which holds functionality for all things HTTP requests.
| `status_code` | Specified when predefined error handlers are run. Using the keyword in handlers and middlewares for requests not invoking error handlers should preferably be specified with a default value to ensure it will work on both error handlers and request router handlers.
| `websocket` | Will be added to websocket requests if used.