Fix broken documentation (#2278)

~When looking at the documentation at SPI for this package, I noticed
that the latest published `1.X` release is `1.24.2`,
https://swiftpackageindex.com/grpc/grpc-swift/1.24.2/documentation/grpc.
I'm not sure if this is because stops tracking previous major versions,
once a newer major has been released (notice that `1.24.2` was the last
`1.X` release before `2.0.0`), or if there's some issue with the newer
`1.X` releases? For example, `GRPCCore` is listed in `spi.yml`, but that
target doesn't exist on `1.X`. See
#2279

The documentation for this package contains a few broken links, both
internal and external.

I updated all broken links, except for
https://github.com/grpc/grpc-swift/blob/release/1.x/docs/faqs.md?plain=1#L157
which points to a file that doesn't exist.
I also removed non-existing target `GRPCCore` from `.spi.yml`, and added
a link to SPI in the README.
Last, I removed some unused markdown links.

Co-authored-by: George Barnett <gbarnett@apple.com>

Close server interceptor pipeline before nil-ing out (#2275)

Motivation:

The server interceptor pipeline and context create a retain cycle which
is broken when the RPC is finished. However there's a path through the
async server handler where the interceptor pipeline is nil'd out but not
closed, meaning the retain cycle isn't broken.

Modifications:

- close the pipeline before niling it out

Result:

Fewer leaks

Close server interceptor pipeline before nil-ing out (#2276)

Motivation:

The server interceptor pipeline and context create a retain cycle which
is broken when the RPC is finished. However there's a path through the
async server handler where the interceptor pipeline is nil'd out but not
closed, meaning the retain cycle isn't broken.

Modifications:

- close the pipeline before niling it out

Result:

Fewer leaks

(cherry picked from commit 6a8927d)

Coalesce final DATA frames for some RPCs (#2274)

Motivation:

For clients, end_stream is set on an empty DATA frame to signal the
client half closing. This is completely valid, however, nginx handles
this poorly and can reset the stream if it receives the response before
end_stream for the client.

Modifications:

- When writing messages set end stream of the final DATA frame.
- When flushing, don't emit writes if the client sends a single message,
wait for the end part first.

Result:

Fewer DATA frames, fewer nginx issues

Fix path escaping on Darwin in SwiftPM plugin (regression of #2085) (#…

…2273)

Resolves #2085

---------

Co-authored-by: Emanuel Erben <emanuel.erben@gmail.com>

Remove `PathLike` and use `URL` instead (#2269)

Removes the `PathLike` definition from `GRPCSwiftPlugin` and uses `URL`
instead, as this project has a minimum supported version of Swift 6.1
now.

Shutdown quiesced conn managers when removed from pool (#2268)

Motivation:

In some rare situations the connection manager can leak a promise on
deinit. The connection pool maintains the refs to these managers and
they are only dropped in two situations:

1. when the pool is shutdown
2. when a quiescing connection is removed from the pool

When the pool is shutdown all conn managers are also shutdown (which
will complete all promises stored in its state).

When a conn is going away the conn manager relies on events from the
channel pipeline to inform it that it can close. When it closes the pool
will remove the ref to the conn manager and do a few bits of cleanup. If
the conn closes gracefully then all is well. However, if that isn't the
case then a reconnect may kick in (creating new promises). At this point
there is a conn manager attempting reconnects but which is no longer
managed by the pool: this is a bug in and of itself.

The conn manager is also kept alive by a ref from the channel it is
currently managing (via a channel handler), it's possible that at some
point during the connection lifecycle that that ref is dropped and
there's nothing keeping the conn manager alive, but this is speculative.

The fix for this is straightforward: for conn managers which are
quiescing shut them down when they are removed from the pool.

Modifications:

- Shutdown conn manager when its last connection is dropped

Result:

Fewer leaking promises

Bump version number to 1.27.0 (#2263)

Motivation:

We plan on tagging a release soon.

Modifications:

- Bump the version to 1.27.0

Result:

The version in the default user-agent string will match the released
version.

Add deprecation warnings (#2248)

Motivation:

v2 has moved to a new repo, grpc-swift-2. That's not all that
discoverable.

Modifications:

- Deprecate commonly used high-level types with a link to a forums post
explaining the move.

Result:

Users are notified about the move

Fix decompression of empty messages with a ratio limit (#2246)

Motivation:

The decompressor has a decompression limit to protect against zip bombs.
This can either be absolute or ratio based. It's also possible in gRPC
for a zero length message to be marked as compressed. gRPC attempts to
decompress the zero length message and fails (because zlib wants a
non-zero sized buffer and gRPC won't give it one as the limit is the
buffer size is limited by the `ratio * msg_size` which in this case is
zero).

Modifications:

- If the input to decompress has no length, skip decompression
altogether

Result:

- Can decompress zero length payloads with the ratio limit
- Resolves #2245