kolo docsbeta

Hecho con Kolo

Programas de ejemplo escritos por el equipo de Kolo para mostrar las bibliotecas trabajando juntas. Son demostraciones, no software de producción ni productos.

En esta página

La página de una biblioteca muestra una pieza cada vez. Un ejemplo muestra las piezas trabajando juntas: cómo se encuentra a un peer, dónde se guardan los mensajes, quién puede unirse.

Estos son programas de ejemplo, escritos por el equipo de Kolo para mostrar las bibliotecas trabajando juntas. Son demostraciones, no software de producción ni productos, y están en beta, como las bibliotecas. No son proyectos de terceros. Las bibliotecas tienen la licencia MIT o Apache-2.0, a tu elección; los ejemplos y sus starters tienen solo Apache-2.0.

Los ejemplos

Chat de escritorio

Funcional

Un ejemplo de chat de escritorio hecho con Wails 3. Los mensajes van directamente de peer a peer, o a través de un relay que ejecutas tú cuando dos ordenadores no pueden conectarse directamente, y se guardan en un log cifrado. Un pin opcional los conserva para quien está sin conexión, la gente nueva se une con una invitación, y cada conversación es una sala en una sola lista, con perfiles. Una sala se reconecta sola y nunca se rinde. Es el ejemplo que construyes en el tutorial, paso a paso.

Código fuente

ciranda-dev/kolo-chat-wails3-example

Bibliotecas

Tutorial

Ejemplo de escritorio para compartir archivos

Funcional

Un ejemplo de escritorio hecho con Wails 3. Envía un archivo o una carpeta en una sesión que dos personas abren con un código, y lo recibe al otro lado, con kolo-blobs y kolo-files. Una descarga cortada continúa sola, y funcionan elementos de 100 GB.

Código fuente

ciranda-dev/kolo-share-wails3-example

Bibliotecas

Tutorial

Tablero kanban compartido

Funcional

Un tablero kanban de escritorio hecho con Wails 3 que varias personas editan a la vez, sobre kolo-braid. Cada ordenador se sincroniza directamente con los demás, o a través de un relay que ejecutas tú, los miembros entran con una invitación, y el tablero muestra qué tarjetas están asentadas.

Código fuente

ciranda-dev/kolo-board-wails3-example

Bibliotecas

Tutorial

Ejemplo de escritorio para videollamadas

Funcional

Un ejemplo de escritorio hecho con Wails 3 para llamadas con audio y vídeo. Una persona crea una invitación, y las demás se unen a la llamada con ella. La imagen sigue a la red, de 360p a 1080p, y una llamada vuelve sola tras una conexión caída. Quien organiza la llamada puede sacar a un participante.

Código fuente

ciranda-dev/kolo-meet-wails3-example

Bibliotecas

Tutorial

¿Necesitas un relay o un pin?

Todos los ejemplos necesitan nodos de entrada para encontrar a los demás, y tienen tres modos de red:

  • Red pública (por defecto). Sin ningún flag, el ejemplo usa los dos nodos de entrada públicos que ejecuta Ciranda, incluidos en las bibliotecas. No hay nada que configurar: dos personas en redes distintas se encuentran. Es gratis y sin garantía de disponibilidad mientras Kolo sea una beta.
  • Tu propia red. -bootstrap host:port[,host:port] usa solo tus propios nodos de entrada.
  • Solo este ordenador. -local mantiene todo en 127.0.0.1. Kolo Share, Kolo Meet y Kolo Board lo tienen; Kolo Chat no.

No hay ningún relay ni ningún pin públicos: los dos siguen siendo opcionales y ejecutas los tuyos. Los comandos están en Ejecuta tu propia infraestructura.

Kolo Chat

  • Ventana: una sola lista de salas en la barra lateral, y cada conversación es una sala. La barra lateral se pliega en una columna estrecha. El "+" junto a la lista abre un menú con "Crear una sala" y "Unirse a una sala", cada una en su propio diálogo. Los mensajes de la misma persona con menos de cinco minutos entre ellos van juntos bajo un solo nombre y una sola hora. La ventana no muestra las direcciones de los nodos de entrada públicos.
  • Pin: opcional. Sin él, los mensajes llegan a la gente solo mientras está en línea. Con uno, guarda una copia cifrada de los mensajes para quien está sin conexión: cada miembro deriva las claves de los mensajes de la clave de la conversación, así que un mensaje se lee desde un pin aunque quien lo envió esté sin conexión. El pin necesita una dirección a la que lleguen todos los miembros: el ejemplo nunca llega a un pin a través de un relay.
  • Salas: un ejemplo guarda 64 salas por defecto; -max-conversations lo cambia, de 1 a 256.
  • Estados de la red: una sala muestra su estado como un punto en la lista, bajo su nombre y en una nota: conectando, en línea, reconectando o sin conexión, nunca como un error. Una sala nunca se congela ni se rinde. Cuando ningún nodo de entrada responde, arranca igualmente, trabaja con su propio log y vuelve a preguntar sola, esperando 2 segundos y duplicando hasta 30. Cuando termina la última conexión con un peer, dice "reconectando" durante hasta 45 segundos, vuelve a marcar a los peers, y cada lado hace pull de lo que el otro escribió entretanto. Los mensajes escritos entretanto se guardan en el log de la sala y se muestran una vez, en orden, cuando vuelve la conexión. Un pin al que no se llega se reintenta con una espera creciente.
  • Muchas salas: el ejemplo arranca sus salas de cuatro en cuatro, primero la que está en pantalla, porque un nodo de entrada público deja que una dirección envíe 50 peticiones por segundo.
  • Relay: opcional, para dos ordenadores detrás de NAT estrictos que no pueden conectarse directamente. Cuando la conexión directa falla, la invitación, los mensajes y la sincronización del historial, los nombres y las salas pasan por él, y no puede leerlos.
  • Arranca todos los ejemplos con el mismo relay: -relay host:port@key, repetido o como lista separada por comas, -relay-file, o KOLO_CHAT_RELAYS cuando no se da ninguno de los dos flags; como máximo 16. La invitación no lleva los relays. Ajustes muestra el estado de cada relay.
  • Secretos: la clave de la conversación y el token del pin nunca son flags, porque un flag se ve en la lista de procesos y en el historial del shell. -conversation-key y -pin-token se rechazan con un mensaje que nombra la variable y el archivo. Define KOLO_CHAT_CONVERSATION_KEY y KOLO_CHAT_PIN_TOKEN, o usa -conversation-key-file y -pin-token-file (también KOLO_CHAT_CONVERSATION_KEY_FILE y KOLO_CHAT_PIN_TOKEN_FILE), que leen el secreto de un archivo que solo su dueño puede abrir.
  • Memoria: al arrancar se fija un límite blando de memoria: la mitad de la memoria física, nunca menos de 512 MiB, y 2 GiB cuando no se puede leer la memoria. GOMEMLIMIT lo sustituye.
  • Versión: Ajustes muestra la versión en Acerca de, el tag de git de la compilación; una compilación sin tag muestra dev.

Kolo Share

  • Ventana: una barra lateral con tus sesiones, que se pliega en una columna estrecha, un menú "+" con "Mostrar un código" y "Pegar un código", y una tarjeta con Historial y Ajustes. Una línea discreta dice en qué red está el ejemplo. La otra persona ve un elemento como "preparándose" mientras lo preparas, y esa misma fila pasa a ser la oferta. Las filas muestran el progreso y la velocidad reales, y avisan cuando nada se movió durante un rato.
  • Reanudación: una descarga cortada continúa sola desde los trozos que ya verificó. -resume-for (o KOLO_SHARE_RESUME_FOR) fija cuánto espera bytes que se detuvieron; por defecto, 30 minutos. Los elementos de 64 MiB o más usan un almacén ajustado para datos grandes.
  • Elementos grandes: un elemento de 100 GB funciona. -max-download (o KOLO_SHARE_MAX_DOWNLOAD) es un límite de seguridad, 1 TiB por defecto. El disco se comprueba antes del primer byte, en la carpeta de datos y en la carpeta elegida, y un disco corto termina la transferencia al momento y dice cuánto hace falta y cuánto hay libre. Se reciben hasta 4 elementos de una sesión a la vez.
  • Velocidad: la conexión con un ordenador emparejado marca el ritmo de lo que envía con BBR por defecto, y -congestion reno|cubic|bbr (o KOLO_SHARE_CONGESTION) lo cambia. BBR mantiene una cola fija de 25 a 150 ms y quita ancho de banda a otros flujos, así que pon reno en un enlace compartido. Las ventanas de recepción solo crecen para el ordenador emparejado, y toda otra conexión conserva ventanas pequeñas. Las conexiones de emparejamiento siguen en Reno.
  • Relay: opcional, para dos ordenadores detrás de NAT estrictos que no pueden conectarse directamente. Cuando la conexión directa falla, el emparejamiento, la sesión y sus archivos pasan por él, y no puede leerlos.
  • Pin: no se usa. Una sesión solo mueve archivos mientras los dos ejemplos están abiertas.
  • Arranca los dos ejemplos con el mismo relay: -relay host:port@key, repetido o como lista separada por comas, -relay-file, o KOLO_SHARE_RELAYS cuando no se da ninguno de los dos flags; como máximo 16. Un relay con lista de permitidos nunca guarda un código de emparejamiento, así que un emparejamiento a través de él solo funciona cuando se llega directamente al ordenador que muestra el código.
  • Números de la conexión: las líneas transfer: del log terminan con lo que midió Conn.Stats de kolo-transport en la conexión: el tiempo de ida y vuelta (rtt, min_rtt), la ventana de congestión y los bytes en vuelo (cwnd, in_flight), los paquetes enviados y perdidos y los bytes perdidos, el controlador (cc), la estimación de ancho de banda de BBR (bw_mbs) y los cambios a un camino nuevo (path_changes). No se registra ningún nombre, clave ni dirección.
  • Nombres largos: un nombre o una ruta que este equipo no puede guardar se rechaza antes de la descarga: 255 bytes por nombre en macOS y Linux, y una ruta de 1023 bytes en macOS, 4095 en Linux y 32767 unidades UTF-16 en Windows.
  • Memoria: al arrancar se fija un límite blando de memoria: la mitad de la memoria física, al menos 512 MiB, y 2 GiB cuando no se puede leer la memoria. GOMEMLIMIT lo sustituye.
  • Versión: Ajustes muestra el tag de git de la compilación; una compilación sin tag muestra dev.

Kolo Meet

  • Relay de la llamada: el ejemplo del anfitrión lo ejecuta en cada llamada, y el audio y el vídeo de cada persona pasan por él. No hay nada que instalar.
  • Relay de conexión: opcional, para dos ordenadores detrás de NAT estrictos que no pueden conectarse directamente. Lleva la conexión al relay de la llamada y los enlaces de claves entre participantes, y no puede leerlos. Dáselo a cada ejemplo con -relay, -relay-file o KOLO_MEET_RELAYS; como máximo 16. Un invitado que no llega directamente al anfitrión necesita un relay sin lista de permitidos, porque el relay de la llamada tiene una clave creada para esa llamada.
  • Calidad: la cámara sube y baja sola por una escalera de tres imágenes, 360p, 720p y el techo de -video-size (1080p por defecto): baja al momento cuando la conexión con el relay de la llamada no puede llevar la imagen, y sube tras unos segundos de camino despejado. Con varios invitados decide el mejor camino.
  • Malas conexiones: una llamada intenta durante hasta 60 segundos recuperar su sesión con el relay antes de terminar, y el relay guarda el sitio del invitado durante el mismo tiempo, así que nadie ve salir al invitado. Un vigilante abre una sesión nueva cuando una persona que envía no entrega nada durante 6 segundos. Un espectador que perdió un grupo pide al emisor un fotograma clave.
  • Pin: no se usa. Una llamada no guarda nada para después.
  • El anfitrión puede expulsar a un participante. Las invitaciones que existen en ese momento ya no dejan volver a esa persona; una invitación nueva del anfitrión sí.
  • Invitaciones: la invitación la sirve un segundo nodo de red con una clave propia, y el relay de la llamada solo lo sirven las personas que el anfitrión dejó entrar. Un desconocido con la invitación solo llega al nodo de la invitación, que mantiene los 16 streams entrantes de kolo-transport; las personas de la llamada mantienen 1000. Un anfitrión de esta versión necesita invitados de esta versión.
  • Dibujo: -display-fps (o KOLO_MEET_DISPLAY_FPS) fija las imágenes por segundo que dibuja cada recuadro de la ventana: auto (por defecto: 30 mientras como mucho otras 4 personas muestran video, 15 con más), 30 o 15.
  • Números de la conexión: la línea local del informe de calidad de la llamada, y la de -quality-log, tiene un objeto net con lo que midió kolo-transport en las conexiones con el relay: tiempo de ida y vuelta, pérdidas, ventana de congestión, bytes en vuelo, controlador, estimación de ancho de banda de BBR y cambios de camino. No contiene ninguna dirección ni clave.
  • Memoria: al arrancar se fija un límite blando de memoria de 2 GiB salvo que GOMEMLIMIT esté definido, y el log dice cuál.
  • Versión: el tag de git, en Ajustes, en el estado y en cada paquete; dev en una compilación de desarrollo.

Kolo Board

  • Ventana: una barra lateral con el tablero, que se pliega en una columna estrecha, cuántas tarjetas están asentadas y sincronizando, una línea discreta sobre la red y una tarjeta con Ajustes. La cabecera tiene el nombre del tablero, los miembros y los botones Invitar, Actividad y Miembros.
  • Relay: opcional, para dos ordenadores detrás de NAT estrictos que no pueden conectarse directamente. Si la conexión directa falla, la invitación, la entrada y la sincronización del tablero pasan por él, y no puede leer lo que reenvía.
  • Settlers: un cambio se asienta cuando hay suficientes settlers en línea. El ejemplo admite a cada persona que entra con AdmitOptions.GrowSettlers, que decide quién asienta: con uno o dos miembros solo quien creó el tablero, con tres los tres, con cuatro o más cuatro de ellos, y quienes entran después son miembros simples. La ventana muestra cuántos están en línea, y los cambios siguen sincronizándose mientras hay pocos.
  • Pin: no se usa. Los miembros se sincronizan directamente entre sí mientras están conectados a la vez.
  • Arranca todos los ejemplos con el mismo relay: -relay host:port@key, repetido o como lista separada por comas, -relay-file, o KOLO_BOARD_RELAYS cuando no se da ninguno de los dos flags; como mucho 16. La invitación no lleva los relays. Ajustes muestra el estado de cada relay, y un relay indicado con una clave equivocada se avisa unos segundos después del arranque.
  • Memoria: al arrancar se fija un límite blando de memoria de 2 GiB salvo que GOMEMLIMIT esté definido, y una línea del log nombra el límite.
  • Versión: el tag de git de la compilación; una compilación sin tag, y wails3 dev, dicen dev.

Prueba Kolo Board

Kolo Board es un tablero kanban de escritorio que varias personas editan a la vez, sobre kolo-braid: solo columnas y tarjetas, sin chat, sin comentarios y sin adjuntos. Necesitas Go 1.26 o superior, Node.js con npm y la CLI de Wails 3. Ejecuta los comandos en la carpeta del repositorio.

Una vez: compila el ejemplo.

Terminal
wails3 build

Una vez: crea una carpeta privada para los datos de la demo.

Terminal
mkdir -p -m 700 /tmp/kolo-board-demo

Sin ningún flag el ejemplo entra en la red pública. Los dos comandos de abajo mantienen la demo en este ordenador, con un nodo de entrada propio en loopback (-local hace lo mismo con un solo flag). Terminal 1: Ana. -first hace que su ejemplo también ejecute el nodo de entrada en loopback.

Terminal
./bin/kolo-board -data /tmp/kolo-board-demo/ana -first 127.0.0.1:4000

Terminal 2: Bia.

Terminal
./bin/kolo-board -data /tmp/kolo-board-demo/bia -bootstrap 127.0.0.1:4000

En la ventana de Ana elige un nombre, crea un tablero y genera una invitación. En la ventana de Bia elige un nombre, pega la invitación y entra. Deja abierta la ventana de Ana: es el nodo de entrada. En dos ordenadores, arranca los dos ejemplos sin flags para usar la red pública, o ejecuta un nodo de entrada de kolo-node propio y pasa -bootstrap, como en Ejecuta tu propia infraestructura.

Kolo Playground

Kolo Playground es una herramienta de pruebas privada, no una biblioteca ni uno de los ejemplos. Su braid-peer ejecuta un miembro de kolo-braid como proceso propio, y braid-scenarios arranca varios en 127.0.0.1, cada uno en un directorio temporal, y ejecuta escenarios con varios peers: convergencia, partición y reunión, cambios de membresía simultáneos, escritores que bifurcan su historia, spam, kill -9, dispositivos restaurados y copiados, y miembros que entran tarde. Cada escenario termina con los mismos digests asentados en todos los peers honestos, o con la parada que espera, e imprime un informe de costes. Ejecuta los comandos en la carpeta del repositorio.

Lista los escenarios:

Terminal
go run ./cmd/braid-scenarios -list

Ejecuta uno:

Terminal
go run ./cmd/braid-scenarios -run partition-heal

Ejecuta un peer a mano, como fundador de un braid nuevo en un directorio temporal. Lee comandos por stdin e imprime un objeto JSON por línea:

Terminal
go run ./cmd/braid-peer --first

Prueba el arnés y todos los escenarios cortos:

Terminal
go test ./...

Qué dicen las tarjetas

  • Funcional: el ejemplo funciona y puedes probarlo, y lo seguimos actualizando. Su tarjeta enlaza un tutorial y la página de cada biblioteca que usa. En Kolo Chat y Kolo Meet el tutorial construye el ejemplo. Kolo Share y Kolo Board no tienen una guía paso a paso propia: su tarjeta enlaza el tutorial de su biblioteca principal (kolo-blobs y kolo-files, o kolo-braid), y el código del ejemplo está en su repositorio.
  • En curso: lo estamos construyendo. La tarjeta aún no tiene enlaces, y los tendrá cuando el ejemplo esté listo.

Como todas las bibliotecas de Kolo, estos ejemplos están en beta: siguen a las bibliotecas v0.x y cambian con ellas.