From 7421a71d127e6451b3d74dbbb303557fc6301dcf Mon Sep 17 00:00:00 2001 From: webbrain-one <295484252+webbrain-one@users.noreply.github.com> Date: Thu, 6 Aug 2026 02:45:12 +0300 Subject: [PATCH] docs: add Spanish README --- README.es-ES.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 README.es-ES.md diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..6b5965c --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,224 @@ + + +# 🚧 En construcción + +Este proyecto está actualmente en construcción y sujeto a cambios. + +# Cliente S3 para Zig 🚀 + +[![Zig](https://img.shields.io/badge/Zig-0.13.0-orange.svg)](https://ziglang.org) +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](https://github.com/algoflows/zig-s3) + +Una biblioteca simple y eficiente de cliente S3 para Zig, que soporta AWS S3 y servicios compatibles con S3. + +## 📑 Tabla de contenidos + +- [Características](#features) +- [Prerrequisitos](#prerequisites) +- [Instalación](#installation) +- [Inicio rápido](#quick-start) +- [Referencia de la API](#api-reference) +- [Manejo de errores](#error-handling) +- [Pruebas](#testing) +- [Desarrollo](#development) +- [Contribuir](#contributing) +- [Comunidad](#community) +- [Licencia](#license) + +## ✨ Características + +- ✅ Operaciones básicas de S3 (crear/eliminar buckets, subir/descargar objetos) +- 🔐 Autenticación AWS Signature V4 +- 🔌 Soporte para endpoints personalizados (MinIO, LocalStack, etc.) +- 📝 Soporte de paginación para listar objetos +- 📦 Ayudas de subida convenientes para diferentes tipos de contenido: + - Subida de contenido como cadena de texto + - Serialización y subida de JSON + - Subida de archivos del sistema de archivos +- 🛡️ Implementación segura en memoria usando la biblioteca estándar de Zig +- 🧪 Conjunto de pruebas exhaustivo: + - Pruebas unitarias para todos los componentes + - Pruebas de integración con MinIO + - Activos de prueba para escenarios del mundo real + +## 🔧 Prerrequisitos + +- Zig 0.13.0 o más reciente +- Para pruebas de integración: Docker (opcional, para ejecutar MinIO) + +## 📥 Instalación + +Agrega el paquete a tu `build.zig.zon`: + +```zig +.{ + .name = "your-project", + .version = "0.1.0", + .dependencies = .{ + .s3 = .{ + .url = "https://github.com/algoflows/zig-s3/archive/v0.2.0.tar.gz", + // Don't forget to update hash after publishing + .hash = "...", + }, + }, +} +``` + +Luego en tu `build.zig`: + +```zig +const s3_dep = b.dependency("s3", .{ + .target = target, + .optimize = optimize, +}); +exe.addModule("s3", s3_dep.module("s3")); +``` + +## 🚀 Inicio rápido + +```zig +const std = @import("std"); +const s3 = @import("s3"); + +pub fn main() !void { + var gpa = std.heap.GeneralPurposeAllocator(.{}){}; + defer _ = gpa.deinit(); + const allocator = gpa.allocator(); + + // Initialize client + var client = try s3.S3Client.init(allocator, .{ + .access_key_id = "your-key", + .secret_access_key = "your-secret", + .region = "us-east-1", + // Optional: Use with MinIO or other S3-compatible services + // .endpoint = "http://localhost:9000", + }); + defer client.deinit(); + + // Create bucket + try client.createBucket("my-bucket"); + + // Upload string content + var uploader = client.uploader(); + try uploader.uploadString("my-bucket", "hello.txt", "Hello, S3!"); +} +``` + +## 📚 Referencia de la API + +### S3Client + +La interfaz principal del cliente para operaciones S3. + +```zig +const client = try s3.S3Client.init(allocator, .{ + .access_key_id = "your-key", + .secret_access_key = "your-secret", + .region = "us-east-1", + .endpoint = "http://localhost:9000", // Optional, for S3-compatible services +}); +``` + +### 🪣 Operaciones de Buckets + +- `createBucket(bucket_name: []const u8) !void` +- `deleteBucket(bucket_name: []const u8) !void` +- `listBuckets() ![]BucketInfo` + +### 📦 Operaciones de Objetos + +- `putObject(bucket_name: []const u8, key: []const u8, data: []const u8) !void` +- `getObject(bucket_name: []const u8, key: []const u8) ![]const u8` +- `deleteObject(bucket_name: []const u8, key: []const u8) !void` +- `listObjects(bucket_name: []const u8, options: ListObjectsOptions) ![]ObjectInfo` + +### 📤 ObjectUploader + +Un asistente para subir diferentes tipos de contenido: + +```zig +var uploader = client.uploader(); + +// Upload string content +try uploader.uploadString("my-bucket", "hello.txt", "Hello, World!"); + +// Upload JSON data +const data = .{ .name = "example", .value = 42 }; +try uploader.uploadJson("my-bucket", "data.json", data); + +// Upload file from filesystem +try uploader.uploadFile("my-bucket", "image.jpg", "path/to/local/image.jpg"); +``` + +## ⚠️ Manejo de errores + +La biblioteca utiliza el tipo unión de errores de Zig para un manejo robusto de errores: + +| Error Type | Descripción | +| ---------------------------- | ----------------------------------- | +| `S3Error.InvalidCredentials` | Credenciales de AWS inválidas | +| `S3Error.BucketNotFound` | El bucket solicitado no existe | +| `S3Error.ObjectNotFound` | El objeto solicitado no existe | +| `S3Error.ConnectionFailed` | Problemas de red o de conexión | +| `S3Error.InvalidResponse` | Respuesta inesperada del servicio S3 | + +## 🧪 Pruebas + +### Pruebas unitarias + +Ejecuta el conjunto de pruebas unitarias: + +```bash +zig build test +``` + +### Pruebas de integración + +Las pruebas de integración requieren una instancia de MinIO en ejecución: + +1. Inicia MinIO: + +```bash +docker run -p 9000:9000 minio/minio server /data +``` + +2. Ejecuta las pruebas de integración: + +```bash +zig build integration-test +``` + +Consulta `tests/integration/README.md` para obtener información detallada sobre las pruebas de integración. + +## 🛠️ Desarrollo + +- Escrito en Zig 0.13.0 +- Utiliza solo la biblioteca estándar (sin dependencias externas) +- Seguro en memoria con asignación y limpieza adecuadas +- Sigue la guía de estilo de Zig y las mejores prácticas + +## 🤝 Contribuir + +1. Haz un fork del repositorio +2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`) +3. Realiza tus cambios +4. Agrega pruebas para tus cambios +5. Ejecuta el conjunto de pruebas +6. Crea una solicitud de extracción (pull request) + +## 👥 Comunidad + +- 📫 Reporta problemas en [GitHub Issues](https://github.com/algoflows/zig-s3/issues) +- 💬 Únete a las discusiones en [GitHub Discussions](https://github.com/algoflows/zig-s3/discussions) +- 🌟 ¡Dale una estrella al repositorio si te resulta útil! + +## 📄 Licencia + +Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles. + +## 🙏 Agradecimientos + +- Documentación de AWS S3 +- Documentación de MinIO +- Biblioteca estándar de Zig