diff --git a/Estructura.md b/Estructura.md new file mode 100644 index 0000000..1a52c5d --- /dev/null +++ b/Estructura.md @@ -0,0 +1,103 @@ +# Cómo está organizado el código + +> ⚠ Rama experimental, no oficial. El Oasis oficial es +> https://github.com/epsylon/oasis · [Volver a la portada](Home) + +Esta rama tiene que hacer dos cosas a la vez: añadir funciones y **seguir el ritmo de +epsylon**, que publica una versión cada pocos días. Lo segundo solo sale bien si el +código propio se distingue del suyo y no le estorba. + +--- + +## La regla + +**Upstream no usa ni un solo subdirectorio** en `src/views`, `src/backend`, +`src/models`, `src/client/assets/styles` ni `src/client/assets/translations`: 66 vistas +y 67 modelos, todos planos. La rama sigue esa misma forma, y los mismos nombres: +`*_model.js` para modelos, `*_view.js` para vistas, `*_views.js` cuando son varias. + +## Los ficheros propios + +| Fichero | Qué es | A qué se parece en upstream | +|---|---|---| +| `src/models/karvan_model.js` | Las salas efímeras y su ciclo de vida | `polls_model.js` | +| `src/views/karvan_view.js` | La lista de salas y la sala | `chats_view.js` | +| `src/backend/karvan_routes.js` | Las rutas del módulo | — (ver abajo) | +| `src/client/public/js/karvan.js` | El cliente WebRTC del navegador | `pdf-viewer.js` | +| `src/client/assets/styles/karvan.css` | Los estilos del módulo | `highlight.css` | +| `src/views/identities_view.js` | El selector de identidades | cualquier `*_view.js` | +| `src/backend/accounts.js` | Encontrar y elegir identidades | `nameCache.js` | +| `src/backend/turnCredentials.js` | Credenciales efímeras para TURN | `wallet_addresses.js` | +| `src/client/assets/translations/i18n_fork.js` | Los textos de la rama | junto a `i18n.js` | +| `src/views/hive_views.js` | La interfaz de móvil | `main_views.js` | + +Ese último está aquí **sin dibujar nada**: sus funciones empiezan con +`if (process.env.OASIS_MOBILE !== '1') return "";`. Vive en los dos repositorios para +que `main_views.js` sea idéntico y las actualizaciones de upstream se apliquen una sola +vez. Ver [Diferencias con la versión de móvil](Diferencias). + +## Y lo que se toca de lo suyo + +**Enganches de una línea**, casi siempre: + +```js +// main_views.js +renderKarvanLink() // calcado de renderPollsLink() +``` + +## Las tres decisiones que no son obvias + +### Por qué las rutas van aparte + +Upstream mete **625 rutas** en `backend.js`, en una sola cadena. Ese fichero se +reescribe en cada versión: `+833/-286` líneas en la 0.9.2, `+266/-31` en la 0.9.1. Una +ruta añadida en medio entra en conflicto **cada vez**. + +Las del módulo viven en `karvan_routes.js`, montadas en un router propio que se inserta +antes del de upstream: lo que no casa cae a `next()` y sigue su curso. Es la única +pieza que no imita a una existente, y por un motivo medible. + +### Por qué las traducciones son un overlay + +Upstream tiene once ficheros `oasis_XX.js` y **los reescribe enteros** en cada versión. +`i18n_fork.js` lleva las claves de la rama aparte, y `i18n.js` las mezcla con tres +líneas. Dentro va solo lo propio: los nombres de las categorías no están, porque son +los de epsylon. + +### Por qué Karvan trae su propia hoja de estilos + +Igual que `highlight.css` en upstream: define la forma —las burbujas, los botones +redondos de llamada, la rejilla de vídeo— y no los colores de la interfaz, que los pone +el tema. Ver [Temas](Temas). + +--- + +## Lo que se ha quitado por sobrar + +| Qué | Por qué sobraba | +|---|---| +| `views/fork/` y `translations/fork/` | Subdirectorios propios; upstream no tiene ninguno | +| Una segunda ruta `/legacy/export` | Copia exacta de la del dev, en otro fichero | +| `media-favorites.js` y su JSON | De una versión anterior; nadie lo requería | +| El campo `subtopic` en el foro | Resto de unos subtemas propios que se descartaron | + +--- + +## Cómo comprobarlo + +Contra un clon de upstream de la misma versión: + +```sh +# ficheros propios de la rama +for d in src/backend src/models src/views; do + diff <(ls ../oasis/$d) <(ls $d) | grep '^>' +done + +# subdirectorios que upstream no tiene (no debería salir ninguno) +find src/views src/backend src/models -maxdepth 1 -type d | tail -n +2 + +# líneas añadidas sobre cada fichero suyo +for f in $(git ls-files 'src/**/*.js'); do + [ -f ../oasis/$f ] && n=$(diff ../oasis/$f $f | grep -c '^>') && [ $n -gt 0 ] && echo "$n $f" +done | sort -rn +``` diff --git a/Home.md b/Home.md index 1d7c252..99acf37 100644 --- a/Home.md +++ b/Home.md @@ -27,7 +27,7 @@ Dos cosas, y ninguna cambia la interfaz que ya conoces: El resto es Oasis 0.9.5 tal cual: el menú lateral por grupos del proyecto original, no la rejilla de hexágonos, que es de la versión para móvil. -![Oasis de escritorio](img/08-portada.png) +![Oasis de escritorio](img/11-portada.png) | Página | De qué va | |---|---| @@ -37,6 +37,8 @@ la rejilla de hexágonos, que es de la versión para móvil. | **[Chats](Chats)** | Los chats cifrados, con respuesta citada | | **[Temas](Temas)** | Cómo se ve el módulo con los cuatro temas | | **[Diferencias con la versión de móvil](Diferencias)** | Qué cambia y por qué | +| **[Estructura del código](Estructura)** | Dónde vive cada fichero y por qué ahí | +| **[Si algo va mal](Problemas)** | Los fallos que han pasado de verdad, y su arreglo | | **[Estado](Roadmap)** | Qué funciona y qué no | Todas las capturas de esta wiki están tomadas de esta rama funcionando en un navegador diff --git a/Problemas.md b/Problemas.md new file mode 100644 index 0000000..4497522 --- /dev/null +++ b/Problemas.md @@ -0,0 +1,109 @@ +# Si algo va mal + +> ⚠ Rama experimental, no oficial. El Oasis oficial es +> https://github.com/epsylon/oasis · [Volver a la portada](Home) + +Todo lo de esta página ha pasado de verdad durante el desarrollo. + +--- + +## Los iconos se ven como cuadros vacíos (□) + +![Iconos sin fuente](img/03-menu-lateral.png) + +**No es un fallo de Oasis.** Usa caracteres Unicode poco comunes para los iconos del +menú y a tu sistema le falta una fuente que los cubra. En la captura se ven así los del +menú lateral, menos el reloj de arena de Karvan. + +```sh +sudo apt install fonts-noto-core # Debian, Ubuntu y derivadas +``` + +No afecta a nada más que a cómo se ve. + +## No arranca: falta hyperaxe o algún módulo + +``` +Cannot find module '../../server/node_modules/hyperaxe' +``` + +Faltan las dependencias. Se instalan **dentro de `src/server`**, no en la raíz: + +```sh +cd src/server && npm install +``` + +## Arranca pero el puerto está ocupado + +Si ya tienes un Oasis corriendo, el segundo no puede coger el mismo puerto web ni el de +SSB. Para levantar una segunda instancia —útil para probar llamadas entre dos +identidades—: + +```sh +OASIS_ACCOUNT=pruebas ./oasis.sh gui --host=127.0.0.1 --port=3011 --no-open -- --port=8009 +``` + +Lo que va detrás de `--` se le pasa a la configuración de SSB; ahí es donde se cambia +el puerto del protocolo. + +## Karvan no aparece en el menú + +Míralo en `/modules`: está entre **Jobs** y **L.A.R.P.**. Si su casilla está +desmarcada, el módulo está apagado y su ruta devuelve un error. + +![Karvan en la pantalla de módulos](img/07-modules.png) + +## El panel de llamada se ve descuadrado + +Ya no debería. Hubo un fallo real: un comentario sin cerrar en `karvan.css` anulaba +todo el bloque de la videollamada, y el resultado eran dos cajas vacías enormes y unos +botones cuadrados. Está arreglado. + +Si te pasa algo parecido tras tocar el CSS, comprueba que no has dejado un comentario +abierto: + +```sh +python3 -c " +import re;s=open('src/client/assets/styles/karvan.css').read() +st=re.sub(r'/\*.*?\*/','',s,flags=re.S) +assert '/*' not in st, 'comentario sin cerrar' +assert st.count('{')==st.count('}'), 'llaves descuadradas' +print('ok')" +``` + +## Con el tema claro, las burbujas se ven raras + +**Clear-SNH** usa `!important` en casi todas sus reglas, así que gana sobre cualquier +hoja posterior. Por eso ese tema trae su propio bloque para Karvan, que lo traduce a la +paleta clara. Si añades un tema con `!important`, tendrás que hacer lo mismo. La lista +de clases a cubrir está en [Temas](Temas). + +## La llamada no conecta + +Comprueba, por este orden: + +1. **Que el indicador está en verde.** Si dice *server relay* con el punto gris, los + dos navegadores todavía no se han encontrado. +2. **Que hay otro participante de verdad.** Con uno solo, se enciende tu cámara y poco + más. +3. **Si estáis en redes distintas**, hace falta un TURN. De fábrica no hay ninguno —a + propósito, para no filtrar la IP a un tercero—. Ver [Llamadas](Llamadas). + +En la misma red local debería conectar sin nada más. + +## Cambié de identidad y sigo viendo la anterior + +El cambio **se aplica al reiniciar**. Cierra Oasis y vuelve a arrancarlo. La variable +`OASIS_ACCOUNT` manda sobre lo que diga el selector, así que si arrancas con ella, +ignorará tu elección. Ver [Instalar](Instalar). + +## Aviso serio: no publiques desde dos sitios con la misma identidad + +Si el selector marca en rojo **"Comparte clave con otra identidad"**, esas dos carpetas +tienen el mismo `secret`. + +Un registro de SSB es una cadena firmada y numerada. Si dos sitios publican el número +500 con contenidos distintos, la red ve una bifurcación, deja de replicar el feed y +**eso no se arregla**: se pierde la identidad. + +Tener la copia no hace daño. Publicar desde las dos, sí. diff --git a/_Sidebar.md b/_Sidebar.md index 07bd827..95a0a93 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -15,6 +15,8 @@ --- - [Diferencias con móvil](Diferencias) +- [Estructura del código](Estructura) +- [Si algo va mal](Problemas) - [Estado](Roadmap) --- diff --git a/img/01-karvan-lista.png b/img/01-karvan-lista.png index b0ad2cc..e891323 100644 Binary files a/img/01-karvan-lista.png and b/img/01-karvan-lista.png differ diff --git a/img/02-karvan-sala.png b/img/02-karvan-sala.png index f1f7c34..df95cc1 100644 Binary files a/img/02-karvan-sala.png and b/img/02-karvan-sala.png differ diff --git a/img/08-portada.png b/img/08-portada.png deleted file mode 100644 index dac876c..0000000 Binary files a/img/08-portada.png and /dev/null differ diff --git a/img/11-portada.png b/img/11-portada.png new file mode 100644 index 0000000..a10deab Binary files /dev/null and b/img/11-portada.png differ