Motivation:
The standard library docs are some of the most important docs
but currently very hard to find. I've noticed that even advanced
users have never heard of them and complain about "zero docs".
Moving to java.net.http.HttpClient brings many benefits, including
HTTP/2 support and the ability to make asynchronous requests.
Major additions and changes:
- Introduce a lightweight org.pkl.core.http.HttpClient API.
This keeps some flexibility and allows to enforce behavior
such as setting the User-Agent header.
- Provide an implementation that delegates to java.net.http.HttpClient.
- Use HttpClient for all HTTP(s) requests across the codebase.
This required adding an HttpClient parameter to constructors and
factory methods of multiple classes, some of which are public APIs.
- Manage CA certificates per HTTP client instead of per JVM.
This makes it unnecessary to set JVM-wide system/security properties
and default SSLSocketFactory's.
- Add executor v2 options to the executor SPI
- Add pkl-certs as a new artifact, and remove certs from pkl-commons-cli artifact
Each HTTP client maintains its own connection pool and SSLContext.
For efficiency reasons, It's best to reuse clients whenever feasible.
To avoid memory leaks, clients are not stored in static fields.
HTTP clients are expensive to create. For this reason,
EvaluatorBuilder defaults to a "lazy" client that creates the underlying
java.net.http.HttpClient on the first send (which may never happen).
This change activates the `TYPESAFE_PROJECT_ACCESSORS` feature
preview in Gradle, and switches to such accessors instead of
string-based project references, where possible
Relates-To: apple/pkl#204
Signed-off-by: Sam Gammon <sam@elide.ventures>
The referenced filename should be `ispklTutorialPart3.pkl`, not `pklTutorial.pkl`.
Also, changes dates from 2023 to 2024
Co-authored-by: grant-abbott <gaabbott@apple.com>
Currently, typed objects are only briefly mentioned in the sentence
stating that (typed) objects cannot be amended with new properties, only
existing ones. This is unnecessarily confusing since all examples up
until that point have been concerned with dynamic objects. Since the
tutorial goes on to amend a dynamic object with a new property in the
next section, a reader who isn't yet aware there are two types of
objects might be confused by what seems to be a contradiction.
Running through the tutorial, the amending was stated in the tutorial text but not visible in the tutorial output since `parrot.pkl` was replacing all the members of `pigeon.pkl`.
