#oboard/mio

#Features

• 🚀 Async/Await Support: Built-in async operations with @mio.run
• 🌐 Complete HTTP Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD, CONNECT, TRACE
• 📄 JSON Handling: Seamless JSON parsing and response handling
• 📁 File Downloads: Built-in file download capabilities with custom save paths
• 🌊 Stream Processing: Real-time data streaming with callback support
• 📦 Binary Data Support: Native handling of binary data with unified Bytes interface across all backends
• 🎯 Multi-Backend: Support for Native (libcurl), JavaScript (Fetch API), and WASM
• ⚡ Type Safety: Full MoonBit type system support with error handling
• 🔧 Flexible Options: Headers, credentials, modes, and request customization

#Backend Support

#Native Backend (native, llvm)

• HTTP Engine: libcurl for robust HTTP requests
• Features: All HTTP methods, file downloads, full header support
• Dependencies: Requires libcurl system library
• Performance: Optimized for server-side and native applications

#JavaScript Backend (js)

• HTTP Engine: Fetch API
• Features: Browser and Node.js compatibility
• Dependencies: No external dependencies
• Performance: Optimized for web applications and frontend development

#WebAssembly Backend (wasm, wasm-gc)

• HTTP Engine: WASM-compatible implementation
• Features: Cross-platform WebAssembly support
• Dependencies: WASM runtime environment
• Performance: Optimized for WASM applications

#Installation

{
  "deps": {
    "oboard/mio": "0.3.0"
  }
}

#Quick Start

#Basic GET Request

@mio.run(fn() {
  match (try? @mio.get("https://api.github.com")) {
    Ok(response) => {
      println("Status: " + response.statusCode.to_string())
      println("Response: " + response.text())
    }
    Err(e) => println("Error: " + e.to_string())
  }
})

#POST Request with JSON Data

@mio.run(fn() {
  match (try? @mio.post("https://httpbin.org/post",
    data={
      "name": "MoonBit",
      "version": "0.3.0",
      "features": ["async", "http", "json"]
    })) {
    Ok(response) => {
      println("Posted successfully!")
      println(response.unwrap_json())
    }
    Err(e) => println("Failed: " + e.to_string())
  }
})

#Custom Headers and Options

@mio.run(fn() {
  let headers = {
    "Authorization": "Bearer your-token",
    "User-Agent": "MoonBit-App/1.0",
    "Accept": "application/json"
  }

  match (try? @mio.get("https://api.example.com/data",
    headers=headers,
    credentials=SameOrigin,
    mode=CORS)) {
    Ok(response) => {
      if response.statusCode == 200 {
        let data = response.json()
        // Process your data
      }
    }
    Err(e) => println("Request failed: " + e.to_string())
  }
})

#File Download

@mio.run(fn() {
  // Download with custom filename
  match (try? @mio.download("https://api.github.com/repos/moonbitlang/core",
    save_path="github_repo.json")) {
    Ok(_) => println("File downloaded successfully!")
    Err(e) => println("Download failed: " + e.to_string())
  }

  // Download with dynamic filename based on headers
  match (try? @mio.download("https://example.com/file.zip",
    save_path_fn=fn(headers) {
      match headers.get("content-disposition") {
        Some(disposition) => extract_filename(disposition)
        None => "downloaded_file.zip"
      }
    })) {
    Ok(_) => println("File downloaded with dynamic name!")
    Err(e) => println("Download failed: " + e.to_string())
  }
})

#Stream Requests

@mio.run(fn() {
  // Stream processing with real-time data handling
  let chunks = []

  match (try? @mio.get_stream("https://api.example.com/stream",
    fn(chunk) {
      println("Received chunk: " + chunk)
      chunks.push(chunk)
      // Process each chunk as it arrives
    })) {
    Ok(response) => {
      println("Stream completed with status: " + response.statusCode.to_string())
      println("Total chunks received: " + chunks.length().to_string())
    }
    Err(e) => println("Stream failed: " + e.to_string())
  }
})

#API Reference

#HTTP Methods

• headers?: Map[String, String] - Custom HTTP headers
• credentials?: FetchCredentials - Request credentials (Omit, SameOrigin, Include)
• mode?: FetchMode - Request mode (CORS, NoCORS, SameOrigin, Navigate)

// GET request
(try? @mio.get(url, headers?, credentials?, mode?))

// POST request with body or JSON data
(try? @mio.post(url, body?, data?, headers?, credentials?, mode?))

// Other HTTP methods
(try? @mio.put(url, body?, headers?, credentials?, mode?))
(try? @mio.delete(url, body?, headers?, credentials?, mode?))
(try? @mio.patch(url, body?, headers?, credentials?, mode?))
(try? @mio.options(url, body?, headers?, credentials?, mode?))
(try? @mio.head(url, body?, headers?, credentials?, mode?))
(try? @mio.connect(url, body?, headers?, credentials?, mode?))
(try? @mio.trace(url, body?, headers?, credentials?, mode?))

// Stream request with callback for real-time data processing
(try? @mio.get_stream(url, callback, headers?, credentials?, mode?))

#Response Handling

// HttpResponse methods
response.text()          // Get response as string
response.json()          // Parse JSON (may raise ParseError)
response.unwrap_json()   // Safe JSON parsing (returns Json::null() on error)
response.statusCode      // HTTP status code
response.headers         // Response headers as Map[String, String]
response.data           // Raw response data as Bytes

#Error Handling

• IOError - File system and I/O related errors
• NetworkError - Network and HTTP request errors
• ExecError - Execution and runtime errors

#Advanced Usage

#Custom Request with Full Control

@mio.run(fn() {
  match (try? @mio.request("https://api.example.com/upload",
    http_method=POST,
    body="custom request body",
    headers={
      "Content-Type": "text/plain",
      "X-Custom-Header": "value"
    },
    credentials=Include,
    mode=CORS)) {
    Ok(response) => {
      // Handle response
    }
    Err(NetworkError) => {
      // Handle network errors
    }
  }
})

#Binary Data Handling

@mio.run(fn() {
  // All requests return binary data in response.data
  match (try? @mio.get("https://example.com/image.png")) {
    Ok(response) => {
      // response.data contains raw bytes (unified across all backends)
      @fs.write_bytes_to_file("image.png", response.data)

      // For text content, use response.text()
      let text_content = response.text()
      println("Content: " + text_content)
    }
    Err(e) => println("Failed to download: " + e.to_string())
  }
})

#Examples

• weatherquery - Weather query tool for Chinese locations
  • Fetches real-time weather data from APIs
  • Supports provinces, cities, and districts
  • Cross-platform (native and web)

#Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

#License