Pennybase - BaaS de código abierto ultraligero basado en archivos

• BaaS (Backend-as-a-Service) ultracompacto implementado solo con la biblioteca estándar de Go, en menos de 1,000 líneas de código
• Ofrece funciones backend esenciales similares a Firebase/Supabase/Pocketbase, pero basadas en archivos locales
  • Almacenamiento de datos basado en archivos usando registros versionados en CSV
  • API REST que devuelve JSON
  • Autenticación basada en cookies de sesión y Basic Auth
  • Soporte para RBAC y sistema de permisos basado en propietario
  • Validación de esquemas
  • Renderizado de plantillas basado en plantillas de Go

Cómo funciona

• Almacenamiento de datos

  • Todos los datos se guardan en archivos CSV legibles por humanos, con un registro por fila
  • La primera columna se fija como ID del registro y la segunda como número de versión
  • El método de guardado es append-only: no sobrescribe registros existentes y siempre agrega una nueva fila de versión en cada actualización
  • Al leer, siempre se usa solo la versión más reciente del registro
  • Para búsquedas y actualizaciones rápidas, mantiene en memoria un índice con la información de offset de archivo de los registros en su versión más reciente para cada recurso

    s1,1,_permissions,_id,text,,,^.+$  
    s2,1,_permissions,_v,number,1,,  
    s3,1,_permissions,resource,text,,,^.+$  
    s4,1,_permissions,action,text,,,^.+$  
    s5,1,_permissions,field,text,,,^.*$  
    s6,1,_permissions,role,text,,,^.*$  
    s7,1,_users,_id,text,,,^.+$  
    s8,1,_users,_v,number,1,,  
    s9,1,_users,salt,text,,,  
    s10,1,_users,password,text,,,^.+$  
    s11,1,_users,roles,list,,,  
    s12,1,todo,_id,text,,,^.+$  
    s13,1,todo,_v,number,1,,  
    s14,1,todo,description,text,0,0,".+"  
    s15,1,todo,completed,number,0,1,""  
    

• Gestión de usuarios y permisos

  • La información de autenticación de usuarios y la lista de roles se guardan en el archivo _users.csv

    admin,1,salt,5V5R4S...====,"admin"  
    alice,1,salt,PXHQWN...====,  
    

  • Usa la misma estructura CSV que todos los demás recursos, pero con el nombre de colección _users
  • No es posible crear usuarios vía API; el archivo debe editarse directamente

• Gestión de permisos

  • Las reglas de control de acceso por recurso se definen en _permissions.csv

    p1,1,todo,read,,*,"cualquier usuario autenticado puede leer ToDo"  
    p2,1,todo,create,,*,"cualquier usuario autenticado puede agregar un nuevo ToDo"  
    p3,1,todo,update,owner,"admin,editor","admin/editor puede actualizar ToDo"  
    p4,1,todo,delete,owner,"admin,editor","admin/editor puede eliminar ToDo"  
    

  • Cada fila representa una regla de permisos

API REST

• Proporciona automáticamente una API REST basada en los recursos (colecciones) definidos en _schemas.csv
• GET /api/{resource}?sort_by={field} : consulta todos los registros de ese recurso, con posibilidad de ordenarlos
• GET /api/{resource}/{id} : consulta un solo registro con un ID específico
• POST /api/{resource} : crea un nuevo registro, requiere permiso "create"
• PUT /api/{resource}/{id} : modifica un registro existente, requiere permiso "update"
• DELETE /api/{resource}/{id} : elimina un registro específico, requiere permiso "delete"
• GET /api/events/{resource} : suscribe al stream en tiempo real de server-side events (SSE) de ese recurso, requiere permiso "read"

• Método de autenticación

  • La autenticación de solicitudes API admite Basic Auth o cookies de sesión
  • Creación de cookie de sesión:
    • Enviar una solicitud a POST /api/login con username y password en el body
    • La respuesta incluye una cookie de sesión, que autentica automáticamente las solicitudes posteriores
  • Cierre de sesión:
    • Al llamar a /api/logout, la sesión se invalida y la cookie se elimina

Archivos estáticos y plantillas

• Puede servir directamente archivos estáticos como HTML, CSS y JavaScript ubicados en el directorio static
  • Ejemplo: se puede acceder a static/index.html desde http://dirección-del-servidor/index.html
• Además, también soporta renderizado de plantillas HTML usando el paquete html/template de Go
  • Los archivos de plantilla se ubican en el directorio templates, y al acceder por URL se renderizan automáticamente
• Datos y funciones disponibles dentro de las plantillas
  • .User: información del usuario autenticado actualmente (nil si no está autenticado)
  • .Store: instancia del store de Pennybase (se usa para consultar y listar recursos)
  • .Request: objeto de la solicitud HTTP actual
  • .ID: ID del recurso al que se está accediendo (cuando aplique)
  • .Authorize: función para verificar permisos de acción sobre un recurso específico

Funcionalidad de hooks

• Permite extender el comportamiento con una sola función hook
• La función hook se llama automáticamente en las operaciones de creación (create), modificación (update) y eliminación (delete) de todos los recursos

• Cómo funciona

  • La función hook opera recibiendo los siguientes cuatro argumentos:
    • trigger: tipo de acción (ej.: create, update, delete)
    • resource: nombre del recurso objetivo
    • user: información del usuario que ejecuta la solicitud
    • res: datos del recurso que se modifica
  • En el punto de hook se puede agregar validación adicional o modificar datos
    • Por ejemplo, al crear un recurso de mensajes, puede rellenar automáticamente el autor y la fecha de creación
    • Si la función hook retorna un error, la acción se detiene de inmediato y se devuelve una respuesta de error al cliente
    • Esto permite implementar diversa lógica personalizada, como verificaciones extra de permisos, corrección automática de datos o disparo de eventos externos

Limitaciones y consideraciones

• Toda la gestión de usuarios/permisos/esquemas requiere editar directamente archivos CSV
• No es adecuado para datos a gran escala, bifurcaciones complejas de permisos o entornos distribuidos de alto rendimiento
• Funciona sin bibliotecas externas, únicamente con código estándar de Go (orientado a aprendizaje/uso simple)
• Licencia MIT; el código fuente y la estructura pueden usarse libremente
• Se agradecen las contribuciones, pero se pide mantener la simplicidad/claridad del código. En adelante, se priorizará más la corrección de errores que la adición de nuevas funciones

[nemorize]

guau...