From 84813ed0daa199109c3990a8cbec11f79629dc9a Mon Sep 17 00:00:00 2001 From: Reed von Redwitz Date: Thu, 9 Apr 2026 13:12:52 +0200 Subject: [PATCH 1/2] chore: standardize README and fix SECURITY.md --- CLAUDE.md | 3 +- README.md | 89 +++++++++++++++++++++++++++++++++++--------- SECURITY.md | 2 +- docs/CODEBASE_MAP.md | 2 +- 4 files changed, 74 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a38d6a1..57dde14 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ Spawn is a Java 25 framework for programmatically launching and controlling processes, JVMs, and Docker containers. It provides a unified abstraction (`Platform` / `Application` / `Process`) over different execution environments. The core pattern: define a `Specification`, call `platform.launch(spec)`, get back an `Application` with `CompletableFuture`-based lifecycle hooks. -**Stack**: Java 25, Maven, Jackson, junixsocket, proprietary `build.base.*` and `build.codemodel.injection` +**Stack**: Java 25, Maven, Jackson, junixsocket, `build.base.*` and `build.codemodel.injection` **Structure**: 8 Maven modules in a monorepo, each mapping to a JPMS module: - `spawn-option` → shared option types @@ -32,5 +32,4 @@ Tests requiring Docker are gated by `@EnabledIf("isDockerAvailable")`. The `spaw - All option types are immutable with static `of(...)` factories and `@Default` annotated defaults - `Customizer` inner classes on `Application` interfaces are auto-discovered and applied at launch - Launcher registry: `META-INF/` properties files map `Application=Launcher` -- Use `Brian Oliver Java style` for all code in this repo (see `brian-oliver-java-style` skill) - Checkstyle enforced: no tabs, no star imports, final locals, no asserts, braces required diff --git a/README.md b/README.md index 8572dd6..a5726bc 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,96 @@ # spawn +A Java framework for programmatically launching and controlling processes, JVMs, and Docker containers. -build.spawn: A framework to programmatically launch and control processes, applications, services and containers +[![CI](https://github.com/Workday/spawn.build/actions/workflows/main-pull-request.yml/badge.svg)](https://github.com/Workday/spawn.build/actions/workflows/main-pull-request.yml) +[![Maven Central](https://img.shields.io/maven-central/v/build.spawn/spawn-application)](https://central.sonatype.com/artifact/build.spawn/spawn-application) +[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -When using this framework to launch Docker containers, the following JVM command-line argument must be added -(with Java 25+): +## Overview -```bash - --enable-native-access=ALL-UNNAMED +`spawn` provides a unified abstraction over local processes, JVMs, and Docker containers. Define a +`Specification`, call `platform.launch(spec)`, and get back an `Application` with +`CompletableFuture`-based lifecycle hooks — regardless of the underlying execution environment. + +## Modules + +| Module | Purpose | +|--------|---------| +| `spawn-option` | Shared option types | +| `spawn-application` | Core abstractions: Platform, Application, Process, Specification, Customizer | +| `spawn-application-composition` | Multi-application topology management | +| `spawn-jdk` | JDK launch abstractions and SpawnAgent for two-way JVM communication | +| `spawn-local-platform` | Local OS process launcher (`LocalMachine`) | +| `spawn-local-jdk` | JDK detection and `LocalJDKLauncher` | +| `spawn-docker` | Docker Engine API interfaces | +| `spawn-docker-jdk` | JDK HTTP Client-based Docker implementation (unix socket via junixsocket) | + +## Requirements + +- Java 25+ +- Maven (wrapper included — no separate install needed) +- Docker (only required for `spawn-docker` / `spawn-docker-jdk` modules) + +## Using this Library + +Add individual modules as dependencies. All modules share the same version: + +```xml + + build.spawn + spawn-application + VERSION + ``` -On MacOS (and linux), local machine access to the Docker Engine may be restricted to prevent read and write access to -the docker.socket. To ensure access to the Docker Engine, the permissions for the following files may need to be -increase. +Replace `VERSION` with the latest version shown in the Maven Central badge above. + +When using the Docker modules, add the following JVM flag (Java 25+): ``` -sudo chmod 660 ~/Library/Containers/com.docker.docker/Data/docker.raw.sock +--enable-native-access=ALL-UNNAMED ``` -and +On macOS and Linux, access to the Docker socket may require a permissions adjustment: -``` +```bash +sudo chmod 660 ~/Library/Containers/com.docker.docker/Data/docker.raw.sock sudo chmod 660 /var/run/docker.sock ``` -It's also possible that the symbolic link to `/var/run/docker.sock` may need to be recreated. +If `/var/run/docker.sock` is missing, recreate the symlink: -``` +```bash sudo ln -s ~/Library/Containers/com.docker.docker/Data/docker.raw.sock /var/run/docker.sock ``` -## Running Tests +## Building from Source -The Docker integration tests (`SessionTests`) require several images to be present in the local Docker cache before running. +```bash +./mvnw clean install +``` -Pre-pull them once using: +To build a custom version: + +```bash +./mvnw -Drevision=x.y.z-SNAPSHOT-my-name clean install +``` + +### Running Tests + +Docker integration tests require several images to be present in the local cache. Pre-pull them once before running: ```bash docker pull alpine:latest && docker pull rabbitmq:latest && docker pull nginx:latest ``` -Without this step, the test setup (`@BeforeAll`) will attempt to pull these images on demand, which blocks the tests -for several minutes and may fail due to transient registry (timeout) errors. +## Contributing + +Code style is enforced by Checkstyle: no tabs, no star imports, final locals and parameters, braces +required on all blocks, no `assert` statements. Import order: third-party, standard Java, then +static. IntelliJ configuration is at `config/intellij/CodeStyle.xml`. + +Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/). + +## License + +Apache 2.0 — see [LICENSE](LICENSE) diff --git a/SECURITY.md b/SECURITY.md index 1c4eb82..246c950 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,7 +15,7 @@ This is a Workday sponsored project hosted on GitHub. To report a security vulnerability, please **do not** open a public GitHub issue. Instead: -1. Navigate to the [Security Advisories](https://https://github.com/workday/spawn.build/security/advisories) page for +1. Navigate to the [Security Advisories](https://github.com/workday/spawn.build/security/advisories) page for this repository and click **Report a vulnerability**. 2. Alternatively, contact the project maintainers directly by emailing the developers. diff --git a/docs/CODEBASE_MAP.md b/docs/CODEBASE_MAP.md index 84d7688..1c4e14b 100644 --- a/docs/CODEBASE_MAP.md +++ b/docs/CODEBASE_MAP.md @@ -372,7 +372,7 @@ Server (listens on spawn:// URI) ## Conventions -### Brian Oliver Java Style +### Code Style - No tabs (spaces only), enforced by Checkstyle - No star imports - Final locals where possible From 6c91207f9cca18e4c3de4f2a125921cbb48aaf4c Mon Sep 17 00:00:00 2001 From: Reed von Redwitz Date: Thu, 9 Apr 2026 13:15:21 +0200 Subject: [PATCH 2/2] drop junixsocket reference --- CLAUDE.md | 4 ++-- README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 57dde14..f80c619 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ Spawn is a Java 25 framework for programmatically launching and controlling processes, JVMs, and Docker containers. It provides a unified abstraction (`Platform` / `Application` / `Process`) over different execution environments. The core pattern: define a `Specification`, call `platform.launch(spec)`, get back an `Application` with `CompletableFuture`-based lifecycle hooks. -**Stack**: Java 25, Maven, Jackson, junixsocket, `build.base.*` and `build.codemodel.injection` +**Stack**: Java 25, Maven, Jackson, `build.base.*` and `build.codemodel.injection` **Structure**: 8 Maven modules in a monorepo, each mapping to a JPMS module: - `spawn-option` → shared option types @@ -14,7 +14,7 @@ Spawn is a Java 25 framework for programmatically launching and controlling proc - `spawn-local-platform` → local OS process launcher (`LocalMachine`) - `spawn-local-jdk` → JDK detection + `LocalJDKLauncher` - `spawn-docker` → Docker Engine API interfaces -- `spawn-docker-jdk` → JDK HTTP Client-based Docker implementation (uses `java.net.http` + junixsocket) +- `spawn-docker-jdk` → JDK HTTP Client-based Docker implementation (uses `java.net.http`) For detailed architecture, see [docs/CODEBASE_MAP.md](docs/CODEBASE_MAP.md). diff --git a/README.md b/README.md index a5726bc..1038219 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ A Java framework for programmatically launching and controlling processes, JVMs, | `spawn-local-platform` | Local OS process launcher (`LocalMachine`) | | `spawn-local-jdk` | JDK detection and `LocalJDKLauncher` | | `spawn-docker` | Docker Engine API interfaces | -| `spawn-docker-jdk` | JDK HTTP Client-based Docker implementation (unix socket via junixsocket) | +| `spawn-docker-jdk` | JDK HTTP Client-based Docker implementation | ## Requirements