# AT-Jet Quick Start

Get a Protobuf API server running in 5 minutes.

## Prerequisites

- Rust 1.75+ (required by axum 0.7)
- `protoc` (Protocol Buffers compiler)

```bash
# macOS
brew install protobuf

# Ubuntu/Debian
apt install protobuf-compiler

# Verify installation
protoc --version
```

## Step 1: Create Project

```bash
cargo new my-api
cd my-api
```

## Step 2: Add Dependencies

Edit `Cargo.toml`:

```toml
[package]
name = "my-api"
version = "0.1.0"
edition = "2021"

[dependencies]
at-jet = "0.6"
tokio = { version = "1", features = ["full"] }
prost = "0.13"
anyhow = "1"

[build-dependencies]
prost-build = "0.13"
```

## Step 3: Define Protobuf Schema

Create `proto/user.proto`:

```protobuf
syntax = "proto3";

package myapi;

message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
}

message CreateUserRequest {
  string name = 1;
  string email = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  int32 total = 2;
}
```

## Step 4: Add Build Script

Create `build.rs`:

```rust
fn main() {
    prost_build::compile_protos(&["proto/user.proto"], &["proto/"]).unwrap();
}
```

## Step 5: Write Server

Edit `src/main.rs`:

```rust
use at_jet::prelude::*;

// Include generated protobuf code
pub mod proto {
    include!(concat!(env!("OUT_DIR"), "/myapi.rs"));
}

use proto::{CreateUserRequest, ListUsersResponse, User};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize tracing (unified setup with sensible defaults)
    let _guard = init_tracing(&TracingConfig::default());

    let server = JetServer::new()
        .route("/health", get(health))
        .route("/api/users", get(list_users).post(create_user))
        .route("/api/users/:id", get(get_user))
        .with_cors()
        .with_compression()
        .with_tracing();

    tracing::info!("Server running on http://0.0.0.0:8080");
    server.serve_with_shutdown("0.0.0.0:8080").await?;
    Ok(())
}

async fn health() -> &'static str {
    "OK"
}

async fn list_users() -> ProtobufResponse<ListUsersResponse> {
    let response = ListUsersResponse {
        users: vec![
            User { id: 1, name: "Alice".into(), email: "alice@example.com".into() },
            User { id: 2, name: "Bob".into(), email: "bob@example.com".into() },
        ],
        total: 2,
    };
    ProtobufResponse::ok(response)
}

async fn get_user(Path(id): Path<i32>) -> ProtobufResponse<User> {
    let user = User {
        id,
        name: "Alice".into(),
        email: "alice@example.com".into(),
    };
    ProtobufResponse::ok(user)
}

async fn create_user(
    ProtobufRequest(req): ProtobufRequest<CreateUserRequest>,
) -> ProtobufResponse<User> {
    let user = User {
        id: 100,
        name: req.name,
        email: req.email,
    };
    ProtobufResponse::created(user)
}
```

## Step 6: Run

```bash
cargo run
```

## Step 7: Test

### Using JetClient (Rust)

Create `examples/client.rs`:

```rust
use at_jet::prelude::*;

pub mod proto {
    include!(concat!(env!("OUT_DIR"), "/myapi.rs"));
}

use proto::{CreateUserRequest, ListUsersResponse, User};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = JetClient::new("http://localhost:8080")?;

    // GET request
    let users: ListUsersResponse = client.get("/api/users").await?;
    println!("Total users: {}", users.total);

    // GET with path parameter
    let user: User = client.get("/api/users/1").await?;
    println!("User: {} ({})", user.name, user.email);

    // POST request
    let req = CreateUserRequest {
        name: "Charlie".into(),
        email: "charlie@example.com".into(),
    };
    let created: User = client.post("/api/users", &req).await?;
    println!("Created user ID: {}", created.id);

    Ok(())
}
```

Run with:

```bash
cargo run --example client
```

### Using curl

```bash
# Health check
curl http://localhost:8080/health

# List users (Protobuf response - binary)
curl -H "Accept: application/x-protobuf" http://localhost:8080/api/users

# With JSON (requires debug key - see User Guide)
```

## Next Steps

- [User Guide](USER_GUIDE.md) - Complete feature documentation
- [Architecture](ARCHITECTURE.md) - Design decisions and rationale
- [Examples](../examples/) - More code examples

### Optional Features

Once your basic server is running, consider enabling:

```toml
# Prometheus metrics
at-jet = { version = "0.6", features = ["metrics"] }

# Jaeger distributed tracing
at-jet = { version = "0.6", features = ["tracing-otel"] }

# JWT authentication middleware
at-jet = { version = "0.6", features = ["jwt"] }

# In-memory session management
at-jet = { version = "0.6", features = ["session"] }
```

See [User Guide](USER_GUIDE.md) for details on each feature.

## Common Issues

### `protoc not found`

Install Protocol Buffers compiler:

```bash
# macOS
brew install protobuf

# Ubuntu
sudo apt install protobuf-compiler
```

### Build fails with prost errors

Ensure your `proto/` directory exists and contains valid `.proto` files.

### Connection refused

Make sure the server is running before testing with the client.
