Merge pull request #11436 from Turbo87/og-image

Add OpenGraph image generation crate

Author: Turbo87

.github/workflows/ci.yml

@@ -23,10 +23,14 @@ env:
   CARGO_DENY_VERSION: 0.18.3
   # renovate: datasource=crate depName=cargo-machete versioning=semver
   CARGO_MACHETE_VERSION: 0.8.0
+  # renovate: datasource=github-releases depName=shssoichiro/oxipng versioning=semver
+  OXIPNG_VERSION: 9.1.5
   # renovate: datasource=npm depName=pnpm
   PNPM_VERSION: 10.12.4
   # renovate: datasource=docker depName=postgres
   POSTGRES_VERSION: 16
+  # renovate: datasource=github-releases depName=typst/typst versioning=semver
+  TYPST_VERSION: 0.13.1
   # renovate: datasource=pypi depName=zizmor
   ZIZMOR_VERSION: 1.11.0
 
@@ -172,6 +176,27 @@ jobs:
       # Remove the Android SDK to free up space
       - run: sudo rm -rf /usr/local/lib/android
 
+      - name: Install Typst
+        run: |
+          wget -q "https://github.com/typst/typst/releases/download/v${TYPST_VERSION}/typst-x86_64-unknown-linux-musl.tar.xz"
+          tar -xf "typst-x86_64-unknown-linux-musl.tar.xz"
+          sudo mv "typst-x86_64-unknown-linux-musl/typst" /usr/local/bin/
+          rm -rf "typst-x86_64-unknown-linux-musl" "typst-x86_64-unknown-linux-musl.tar.xz"
+          typst --version
+
+      - name: Install oxipng
+        run: |
+          wget -q "https://github.com/shssoichiro/oxipng/releases/download/v${OXIPNG_VERSION}/oxipng-${OXIPNG_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          tar -xf "oxipng-${OXIPNG_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          sudo mv "oxipng-${OXIPNG_VERSION}-x86_64-unknown-linux-musl/oxipng" /usr/local/bin/
+          rm -rf "oxipng-${OXIPNG_VERSION}-x86_64-unknown-linux-musl" "oxipng-${OXIPNG_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          oxipng --version
+
+      - name: Download Fira Sans font
+        run: |
+          wget -q "https://github.com/mozilla/Fira/archive/4.202.zip"
+          unzip -q "4.202.zip"
+
       - uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0
         with:
           save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -183,6 +208,10 @@ jobs:
 
       - run: cargo build --tests --workspace
       - run: cargo test --workspace
+        env:
+          # Set the path to the Fira Sans font for Typst.
+          # The path is relative to the `crates_io_og_image` crate root.
+          TYPST_FONT_PATH: ../../Fira-4.202/otf
 
   frontend-lint:
     name: Frontend / Lint

Cargo.lock

@@ -0,0 +1,26 @@
+[package]
+name = "crates_io_og_image"
+version = "0.0.0"
+edition = "2024"
+license = "MIT OR Apache-2.0"
+description = "OpenGraph image generation for crates.io"
+
+[lints]
+workspace = true
+
+[dependencies]
+anyhow = "=1.0.98"
+bytes = "=1.10.1"
+crates_io_env_vars = { path = "../crates_io_env_vars" }
+reqwest = "=0.12.21"
+serde = { version = "=1.0.219", features = ["derive"] }
+serde_json = "=1.0.140"
+tempfile = "=3.20.0"
+thiserror = "=2.0.12"
+tokio = { version = "=1.45.1", features = ["process", "fs"] }
+tracing = "=0.1.41"
+
+[dev-dependencies]
+insta = "=1.43.1"
+tokio = { version = "=1.45.1", features = ["macros", "rt-multi-thread"] }
+tracing-subscriber = { version = "=0.3.19", features = ["env-filter", "fmt"] }

crates/crates_io_og_image/Cargo.toml

@@ -0,0 +1,94 @@
+# crates_io_og_image
+
+A Rust crate for generating Open Graph images for crates.io packages.
+
+![Example OG Image](src/snapshots/crates_io_og_image__tests__generated_og_image.snap.png)
+
+## Overview
+
+`crates_io_og_image` is a specialized library for generating visually appealing Open Graph images for Rust crates. These images are designed to be displayed when crates.io links are shared on social media platforms, providing rich visual context about the crate including its name, description, authors, and key metrics.
+
+The generated images include:
+
+- Crate name and description
+- Tags/keywords
+- Author information with avatars (when available)
+- Key metrics (releases, latest version, license, lines of code, size)
+- Consistent crates.io branding
+
+## Requirements
+
+- The [Typst](https://typst.app/) CLI must be installed and available in your `PATH`
+
+## Usage
+
+### Basic Example
+
+```rust
+use crates_io_og_image::{OgImageData, OgImageGenerator, OgImageAuthorData, OgImageError};
+
+#[tokio::main]
+async fn main() -> Result<(), OgImageError> {
+    // Create a generator instance
+    let generator = OgImageGenerator::default();
+
+    // Define the crate data
+    let data = OgImageData {
+        name: "example-crate",
+        version: "1.2.3",
+        description: Some("An example crate for testing OpenGraph image generation"),
+        license: Some("MIT/Apache-2.0"),
+        tags: &["example", "testing", "og-image"],
+        authors: &[
+            OgImageAuthorData::with_url(
+                "Turbo87",
+                "https://avatars.githubusercontent.com/u/141300",
+            ),
+        ],
+        lines_of_code: Some(2000),
+        crate_size: 75,
+        releases: 5,
+    };
+
+    // Generate the image
+    let temp_file = generator.generate(data).await?;
+
+    // The temp_file contains the path to the generated PNG image
+    println!("Image generated at: {}", temp_file.path().display());
+
+    Ok(())
+}
+```
+
+## Configuration
+
+The path to the Typst CLI can be configured through the `TYPST_PATH` environment variables.
+
+## Development
+
+### Running Tests
+
+```bash
+cargo test
+```
+
+Note that some tests require Typst to be installed and will be skipped if it's not available.
+
+### Example
+
+The crate includes an example that demonstrates how to generate an image:
+
+```bash
+cargo run --example test_generator
+```
+
+This will generate a test image in the current directory. This will also test the avatar fetching functionality, which requires network access and isn't run as part of the automated tests.
+
+## License
+
+Licensed under either of:
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.

crates/crates_io_og_image/README.md

@@ -0,0 +1,57 @@
+use crates_io_og_image::{OgImageAuthorData, OgImageData, OgImageGenerator};
+use tracing::level_filters::LevelFilter;
+use tracing_subscriber::{EnvFilter, fmt};
+
+fn init_tracing() {
+    let env_filter = EnvFilter::builder()
+        .with_default_directive(LevelFilter::DEBUG.into())
+        .from_env_lossy();
+
+    fmt().compact().with_env_filter(env_filter).init();
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    init_tracing();
+
+    println!("Testing OgImageGenerator...");
+
+    let generator = OgImageGenerator::from_environment()?;
+    println!("Created generator from environment");
+
+    // Test generating an image
+    let data = OgImageData {
+        name: "example-crate",
+        version: "1.2.3",
+        description: Some("An example crate for testing OpenGraph image generation"),
+        license: Some("MIT/Apache-2.0"),
+        tags: &["example", "testing", "og-image"],
+        authors: &[
+            OgImageAuthorData::new("example-user", None),
+            OgImageAuthorData::with_url(
+                "Turbo87",
+                "https://avatars.githubusercontent.com/u/141300",
+            ),
+        ],
+        lines_of_code: Some(2000),
+        crate_size: 75,
+        releases: 5,
+    };
+    match generator.generate(data).await {
+        Ok(temp_file) => {
+            let output_path = "test_og_image.png";
+            std::fs::copy(temp_file.path(), output_path)?;
+            println!("Successfully generated image at: {output_path}");
+            println!(
+                "Image file size: {} bytes",
+                std::fs::metadata(output_path)?.len()
+            );
+        }
+        Err(error) => {
+            println!("Failed to generate image: {error}");
+            println!("Make sure typst is installed and available in PATH");
+        }
+    }
+
+    Ok(())
+}

crates/crates_io_og_image/examples/test_generator.rs

@@ -0,0 +1,56 @@
+//! Error types for the crates_io_og_image crate.
+
+use std::path::PathBuf;
+use thiserror::Error;
+
+/// Errors that can occur when generating OpenGraph images.
+#[derive(Debug, Error)]
+pub enum OgImageError {
+    /// Failed to find or execute the Typst binary.
+    #[error("Failed to find or execute Typst binary: {0}")]
+    TypstNotFound(#[source] std::io::Error),
+
+    /// Environment variable error.
+    #[error("Environment variable error: {0}")]
+    EnvVarError(anyhow::Error),
+
+    /// Failed to download avatar from URL.
+    #[error("Failed to download avatar from URL '{url}': {source}")]
+    AvatarDownloadError {
+        url: String,
+        #[source]
+        source: reqwest::Error,
+    },
+
+    /// Failed to write avatar to file.
+    #[error("Failed to write avatar to file at {path:?}: {source}")]
+    AvatarWriteError {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+
+    /// JSON serialization error.
+    #[error("JSON serialization error: {0}")]
+    JsonSerializationError(#[source] serde_json::Error),
+
+    /// Typst compilation failed.
+    #[error("Typst compilation failed: {stderr}")]
+    TypstCompilationError {
+        stderr: String,
+        stdout: String,
+        exit_code: Option<i32>,
+    },
+
+    /// I/O error.
+    #[error("I/O error: {0}")]
+    IoError(#[from] std::io::Error),
+
+    /// Temporary file creation error.
+    #[error("Failed to create temporary file: {0}")]
+    TempFileError(std::io::Error),
+
+    /// Temporary directory creation error.
+    #[error("Failed to create temporary directory: {0}")]
+    TempDirError(std::io::Error),
+}