-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Distribute Android component through pre-built Maven local repository
- Loading branch information
1 parent
073b82a
commit a2a2ce3
Showing
12 changed files
with
204 additions
and
61 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,7 @@ | ||
[workspace] | ||
members = ["rustls-platform-verifier"] | ||
members = [ | ||
"android-release-support", | ||
"rustls-platform-verifier", | ||
] | ||
|
||
resolver = "2" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
# How-to release `rustls-platform-verifier` | ||
|
||
This document records the steps to publish new versions of the crate since it requires non-trivial preperation and ordering | ||
that needs to be remembered due to the Android component's distribution. | ||
|
||
## Steps | ||
|
||
1. Update main crate'a version in `rustls-platform-verifier/Cargo.toml`, and in any additional places. | ||
2. If any non-test changes have been made to the `android` directory since the last release: | ||
1. Update Android artifact version in `android-release-support/Cargo.toml` | ||
2. Bump dependency version of the Android support crate in `rustls-platform-verifier/Cargo.toml` to match the new one | ||
3. Commit version increase changes on the release branch | ||
4. Run `ci/package_android_release.sh` in a UNIX compatible shell | ||
5. (Optional) `cargo publish -p rustls-platform-verifier-android --dry-run` | ||
6. (Optional) Inspect extracted archive to ensure the local Maven repository artifacts are present | ||
7. Publish the Android artifacts' new version: `cargo publish -p rustls-platform-verifier-android` | ||
3. Commit main crate's version increase on the release branch | ||
4. Publish the main crate's new version: `cargo publish -p rustls-platform-verifier` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
[package] | ||
name = "rustls-platform-verifier-android" | ||
version = "0.1.0" | ||
description = "The internal JVM support component of the rustls-platform-verifier crate. You shouldn't depend on this directly." | ||
repository = "https://github.com/1Password/rustls-platform-verifier" | ||
license = "MIT OR Apache-2.0" | ||
edition = "2021" | ||
|
||
# Explicitly include the Maven local repository for the Android component. | ||
# While not checked into the repository, it is generated for releases and other contexts. | ||
include = [ | ||
"src/*", | ||
"maven/pom.xml", | ||
"maven/rustls/rustls-platform-verifier/**/", | ||
"maven/rustls/rustls-platform-verifier/maven-metadata-local.xml", | ||
] | ||
|
||
[dependencies] |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
<?xml version="1.0" encoding="UTF-8"?> | ||
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0" | ||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | ||
<modelVersion>4.0.0</modelVersion> | ||
<groupId>rustls</groupId> | ||
<artifactId>rustls-platform-verifier</artifactId> | ||
<version>$VERSION</version> | ||
<packaging>aar</packaging> | ||
<description>The internal JVM support component of the rustls-platform-verifier Rust crate</description> | ||
</project> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
//! # rustls-platform-verifier-android | ||
//! | ||
//! This crate is an implementation detail of the actual [rustls-platform-verifier](https://github.com/rustls/rustls-platform-verifier) crate. | ||
//! | ||
//! It contains no Rust code and is solely intended as a convenient delivery mechanism for the supporting Kotlin code that the main crate | ||
//! requires to perform TLS certificate validation using Android's APIs. | ||
//! | ||
//! Other crates should not directly depend on this crate in any way, as nothing about it is considered stable and probably useless elsewhere. | ||
//! | ||
//! ## Details | ||
//! | ||
//! Note: Everything in this section is subject to change at any time. Semver may not be followed either. | ||
//! | ||
//! ### Why? | ||
//! | ||
//! It was the best middle ground between several tradeoffs. The important ones, in priority order, are: | ||
//! - Automatically keeping component versions in sync | ||
//! - Allowing well-tested and well-known `cargo` dependency management patterns to apply everywhere | ||
//! - Providing a smooth developer experience as an Android consumer of `rustls-platform-verifier` | ||
//! | ||
//! Firstly, what alternatives are available for distributing the component? The other two known are source distribution n some form (here, it will be through crates.io) | ||
//! and Maven Central. Starting with the first, its become infeasible due to toolchain syncing requirements. If the Android component is | ||
//! built as part of the host app's Gradle build, then it becomes subject to any Gradle or AGP incompatibilites/requirements. In practice this means | ||
//! the AGP version between this project and the main application have to match all the time. Sometimes this works, but it becomes challenging/unfeasible | ||
//! during yearly toolchain/SDK upgrades and is not maintainable long term. Note that this is the _only_ option in this section which retains compatible | ||
//! with Cargo's Git dependency patching. | ||
//! | ||
//! Next, Maven Central. This is considered the standard way of distributing public Android dependencies. There are two downsides to this | ||
//! approach: version synchronization and publishing overhead. Version syncing is the hardest part: There's not a good way to know what version | ||
//! a crate is that doesn't hurt the Cargo part of the build or damage functionality. So instead of making assumptions at runtime, we would need to do | ||
//! clunky and manual version counting with an extra error case. Less importantly, the admin overhead of Maven Central is non-zero so its good to avoid | ||
//! if possible for such a small need. | ||
//! | ||
//! It is also worth calling out a third set of much worse options: requiring users to manually download and install the Android component | ||
//! on each update, which magnifies the version syncing problem with lots of user overhead and then deleting the component outright. A rewrite | ||
//! could be done with raw JNI calls, but this would easily be 3x the size of the existing implementation and require huge amounts of `unsafe` | ||
//! to review then audit. | ||
//! | ||
//! ### The solution | ||
//! | ||
//! The final design was built to avoid the pitfalls the previous two options mentioned. To build it, we rely on CI and packaging scripts to build | ||
//! the Android component into a prebuilt AAR file before creating a release. Next, a [on-disk Maven repository](https://maven.apache.org/repositories/local.html) | ||
//! is hosted inside of this repository. Only the unchanging file structure of it is kept checked-in, to avoid churn. The remaining parts are filled in | ||
//! during the packaging/release process, before being included in `cargo package` via an `include` Cargo.toml directive. Finally, once the repository has had | ||
//! its artifacts added, this crate is published to crates.io containing it. Then, the main crate ensures its downloaded when an Android target is compiled for via | ||
//! a platform-specific dependency. | ||
//! | ||
//! On the Gradle side, we include a very small snippet of code for users to include in their `settings.gradle` file to dyanmically locate the local maven repository | ||
//! on disk automatically based off Cargo's current version of it. The script is configuration cache friendly and doesn't impact performance either. When the script | ||
//! is run, it finds the cargo-cached download of the crate and tells Gradle it can find the `rustls-platform-verifier` Android component there when it gets sourced | ||
//! into the hosting application's build tree. | ||
//! | ||
//! ### Precompiled artifacts? | ||
//! | ||
//! For some, the notion of shipping something pre-compiled with an existing source distribution might seem incorrect, or insecure. However in this specific case, | ||
//! putting aside the fact shipping Kotlin code doesn't work (see above), there are many reasons this isn't the case: | ||
//! - Shipping pre-compiled artifacts is normal in the Java ecosystem. Maven Central and other package repositories do the same thing and serve `.jar` downloads. | ||
//! - Those not using Android will never download the pre-compiled AAR file. | ||
//! - The artifacts are incredibly easy to reproduce given an identicial compilation toolchain. | ||
//! - The artifacts are not native executables, or raw `.jar` files, so they can't be accidentally executed on a host system. | ||
//! | ||
//! ## Summary | ||
//! | ||
//! In summary, the selected distribution method avoids most of the previous pitfalls while still balancing a good experience for `cargo` annd Gradle users. Some of its | ||
//! positive properties include: | ||
//! - Full compatibility with Cargo's dependency management, including Git patching[^1] | ||
//! - No version checking or synchronization required | ||
//! - Painless and harmless to integrate into an Android app's build system | ||
//! - Low maintenance for the main crate maintainers' | ||
//! | ||
//! [^1]: The Git reference being used must have the local maven repository built and checked-in first. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
#!/usr/bin/env bash | ||
|
||
# This script's purpose is to automate the build + packaging steps for the pre-compiled Android verifier component. | ||
# It works with template files and directories inside the `android-release-support/` part of the repository to setup | ||
# a Maven local repository and then add the pre-compiled AAR file into it for distribution. The results of this packaging | ||
# are then included by `cargo` when publishing `rustls-platform-verifier-android`. | ||
|
||
set -euo pipefail | ||
|
||
if ! type mvn > /dev/null; then | ||
echo "The maven CLI, mvn, is required to run this script." | ||
echo "Download it from: https://maven.apache.org/download.cgi" | ||
exit 1 | ||
fi | ||
|
||
version=$(cat android-release-support/Cargo.toml | grep -m 1 "version = " | tr -d "version= " | tr -d '"') | ||
|
||
echo "Packaging v$version of the Android support component" | ||
|
||
pushd ./android | ||
|
||
./gradlew assembleRelease | ||
|
||
popd | ||
|
||
artifact_name="rustls-platform-verifier-release.aar" | ||
|
||
pushd ./android-release-support | ||
|
||
artifact_path="../android/rustls-platform-verifier/build/outputs/aar/$artifact_name" | ||
|
||
# Ensure no prior artifacts are present | ||
git clean -dfX "./maven/" | ||
|
||
cp ./pom-template.xml ./maven/pom.xml | ||
sed -i "" "s/\$VERSION/$version/" ./maven/pom.xml | ||
|
||
mvn install:install-file -Dfile="$artifact_path" -Dpackaging="aar" -DpomFile="./maven/pom.xml" -DlocalRepositoryPath="./maven/" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters