Nodo comunitario verificado: tres preguntas de elegibilidad antes de una reescritura sin dependencias

Hola equipo de n8n,

Mantengo n8n-nodes-duckduckgo-search, un nodo de búsqueda de DuckDuckGo sin credenciales con aproximadamente 21.000 instalaciones. Me gustaría enviarlo para verificación y he leído los requisitos, en particular la regla de cero dependencias en tiempo de ejecución. Cumplirla significa eliminar cuatro dependencias — axios, duck-duck-scrape, @mozilla/readability y linkedom. Las dos últimas potencian la extracción de texto de artículos del nodo, y reemplazarlas es una reescritura sustancial con un riesgo real de degradación de calidad.

Antes de comprometerme con ese trabajo, hay tres cosas que no pude resolver de la documentación:
1. “No debe ser un nodo existente.” No hay ningún nodo de DuckDuckGo en n8n hoy, y este paquete ya tiene ~21k instalaciones, así que interpreto que la regla no aplica aquí. ¿Es correcto, o también cubre un nodo de comunidad que ya existe?

2. Endpoints no oficiales. DuckDuckGo no publica ninguna API de búsqueda. El nodo utiliza los mismos endpoints HTML/lite y la API pública Instant Answer que usa cualquier biblioteca de DuckDuckGo. Las directrices no abordan los endpoints no oficiales de ninguna manera. ¿Es un nodo construido sobre ellos elegible para verificación en absoluto? Si no, preferiría saberlo antes de empezar.

3. Revisión desde una IP de centro de datos. DuckDuckGo aplica límite de velocidad por IP y responde a una ráfaga con una página de anomalía — HTTP 202 que lleva un CAPTCHA, no un estado de error. Un revisor que pruebe desde infraestructura de nube muy probablemente la alcanzará. El nodo detecta esa página e informa sobre ella explícitamente en lugar de devolver una lista vacía, así que lo que un revisor vería es un mensaje de error en lugar de resultados de búsqueda. ¿Hay una forma de señalar esto antes de una revisión, o una forma preferida de demostrar que el nodo funciona?

Información sobre el paquete

Gracias,
Sam Nodehi

Hola @Sam_Nodehi, mientras esperas una respuesta, aquí hay algunas cosas que podrían ayudarte:

Recursos sugeridos

Automaticamente coincidentes con tu pregunta.

Documentación:

Foro:

@Misha, @Baseman - han ayudado con problemas similares antes, ¿pueden echar un vistazo?

Sugerido automáticamente por el bot comunitario de n8n. Es una prueba piloto - comparte tu opinión aquí.

Pasé por verificación recientemente, así que parte de esto podría transferirse, pero te recomendaría verificarlo con el equipo de n8n. Toma esto como la lectura de un mantenedor en lugar de una sentencia.

Sobre la regla de dependencias, lo que yo aclararía antes de comprometerse con una reescritura es si el empaquetamiento cuenta. La restricción está en lo que npm resuelve e instala en tiempo de ejecución, así que vendimiar tus dependencias en el dist publicado con un empaquetador puede satisfacerlo sin eliminar ninguna funcionalidad. Si esa lectura se sostiene, la legibilidad y linkedom se quedan donde están y evitas completamente el riesgo de regresión. Esa es la diferencia entre un cambio de configuración de compilación y una reescritura, así que vale la pena preguntarlo explícitamente en lugar de asumir de una u otra forma.

Personalmente, eliminamos todas las dependencias externas para obtener verificación e hicimos que usara nuestras APIs en el servidor. Una desventaja es que para nuestro paquete popular GitHub - TurboDocx/html-to-docx: HTML to DOCX converter · GitHub, tendríamos que consumir ciclos de computación en esto y probablemente lo pondríamos en nuestro plan medido.

Sobre la pregunta 3, el problema de la IP del centro de datos: el hecho de que tu nodo detecte la página de anomalía e lo reporte explícitamente en lugar de devolver un arreglo vacío es el comportamiento correcto, y lo pondría cerca de la parte superior del readme en lugar de dejar que un revisor lo descubra. Un revisor que alcance el límite de velocidad y vea un mensaje claro de „DuckDuckGo devolvió una página de anomalía

Gracias, valió la pena investigar esto, porque si el empaquetamiento contara cambiaría toda la decisión. Fui y lo medí en lugar de razonarlo, y la respuesta resulta ser “sí, pero no para estas librerías”.

Tienes razón sobre el campo dependencies. La documentación de reglas propia de n8n lo dice explícitamente, no-runtime-dependencies.md:

Las librerías compartidas deben declararse en peerDependencies (para que el tiempo de ejecución del host las suministre) o empaquetarse en tiempo de compilación en el artefacto publicado.

Y no-restricted-imports.md exime cualquier cosa en devDependencies, con el argumento de que nunca se instala en tiempo de ejecución. Así que mover las librerías a devDependencies y empaquetar las en dist sí que cumple con ambas reglas.

La parte que lo decide es que el análisis tiene dos etapas. Del comentario en scanner/scanner.mjs en @n8n/scan-community-package@0.35.0:

Los globs .ts solo coinciden con la comprobación de procedencia del repositorio de fuente, la etapa del tarball verifica .js compilado y el package.json publicado solamente.

Así que el paquete en sí se verifica, y no-restricted-globals, no-dangerous-functions y no-console se aplican a lo que haya emitido el empaquetador.

Medido, no asumido. Empaqué exactamente mis tres dependencias problemáticas, axios, @mozilla/readability, linkedom, con esbuild (salida de 1,1 MB), luego ejecuté la configuración de análisis propia de n8n sobre él a través del analyzePackage del escáner:

passed: false
✖ 125 problems (125 errors, 0 warnings)

El desglose: process ×46, globalThis ×8, setTimeout ×15, clearTimeout ×9, setImmediate ×5, console. ×11. Sin eval o new Function, para lo que vale. Y una categoría que no esperaba, los módulos integrados de Node también están bloqueados:

error  Require of 'stream' is not allowed. n8n Cloud does not allow community nodes with dependencies
error  Require of 'util' is not allowed.
error  Require of 'path' is not allowed.

Así que el empaquetamiento es una opción real en general, depende enteramente de lo que contenga el código de la propia librería, pero no rescata nada construido sobre la superficie de la plataforma Node, que son la mayoría de clientes HTTP y todas las implementaciones de DOM. Para mi caso es la eliminación, no un cambio de configuración de compilación, que es la conclusión que esperaba evitar.

Eso también coincide con lo que el equipo le dijo a otro mantenedor en un hilo anterior: eliminar todas las dependencias externas, incluyendo las que usan los propios nodos de n8n.

Otras dos cosas, por si son útiles para cualquiera que lea esto:

El requisito de procedencia es directo una vez configurado, un editor de confianza en npm más id-token: write, sin token en ningún lugar. Una trampa: los editores de confianza tienen una configuración de Acciones permitidas que puede registrarse solo como npm stage publish, que falla con E403 OIDC permission denied for this action después de que la procedencia ya haya sido firmada. Y necesita npm ≥ 11.5.1, mientras que actions/setup-node con Node 22 sigue enviando npm 10.

Hay también un bug que vale la pena señalar: en Windows la etapa de obtención de fuente del escáner falla con una ruta temporal corrupta (tar: C\:\\Users\\...: Cannot open), así que solo se completa la comprobación de procedencia. Un mantenedor de Windows no puede ejecutar el análisis completo localmente.

Sobre la pregunta 3, seguí tu consejo de inmediato. El manejo de la página de anomalías ahora es lo primero en el README, por encima de la lista de características, diciendo qué significa y qué no significa un conjunto de resultados vacío. Tu forma de presentarlo fue exactamente la correcta, y mientras lo escribía descubrí que la garantía no era realmente cierta en una ruta: la búsqueda de imágenes comprobaba el desafío en la solicitud de arranque del token pero no en la solicitud que lleva los resultados, así que un bloqueo allí seguía devolviendo una matriz vacía. Arreglado y probado. Así que gracias dos veces.

Sobre la pregunta 1, esa es mi lectura también. Tu segundo punto es el que no había considerado, si n8n acepta un nodo para un servicio con el que no tienes afiliación. Añadiendo eso a lo que me gustaría que confirmases.

@Sam_Nodehi
@Nicolas_Fry ¡buen trabajo! También aclararía la pregunta del endpoint antes de hacer la reescritura. Dado que DuckDuckGo no proporciona una API de búsqueda oficial, el entorno de prueba del revisor podría ser tan importante como el nodo en sí. Para el problema del centro de datos/IP, estoy de acuerdo en que documentar explícitamente la respuesta 202 y el manejo de anomalías en el README es una buena idea. Le da contexto al revisor en lugar de hacer que una prueba fallida parezca un nodo roto.

Y para el requisito de dependencia, definitivamente obtendría confirmación de n8n sobre si el bundling/vendoring es aceptable antes de eliminar readability y linkedom - eso podría ahorrar mucho trabajo de reescritura innecesario.

Gracias @daniel_Samuel, y tienes razón al insistir en la cuestión del empaquetamiento incluso después de que publiqué la medición, porque la medición responde una pregunta más estrecha de lo que parece.

Lo que establecí es lo que hace el escáner: empaquetar axios, @mozilla/readability y linkedom con esbuild, ejecutar la configuración propia de @n8n/scan-community-package sobre el resultado, y obtienes 125 errores. Todos provienen del código propio de las bibliotecas, process ×46, globalThis ×8, setTimeout ×15, más require('stream'), require('util'), require('path').

Lo que no establece es si ese veredicto es la política. process dentro de una dependencia empaquetada no es el nodo “usando un global restringido” en ningún sentido que una persona reconocería, nadie lo escribió, no es alcanzable desde la propia superficie del nodo, y la regla que incumple existe para evitar que los nodos hagan cosas en n8n Cloud en lugar de evitar que una dependencia exista. Un revisor podría razonablemente leerlo de cualquiera de las dos formas, y solo n8n puede decir cuál es.

Así que pienso que la pregunta que hay que hacerles es más precisa que “¿es aceptable el empaquetamiento?”, que su propia documentación de reglas ya responde, no-runtime-dependencies dice que las bibliotecas compartidas “deben declararse en peerDependencies … o empaquetarse en tiempo de compilación en el artefacto publicado”, y no-restricted-imports exime cualquier cosa en devDependencies. Entre ambas, mover las bibliotecas a devDependencies y empaquetar cumple ambas reglas limpiamente. La pregunta abierta es la etapa después de eso:

¿Vincula el veredicto del escáner sobre código de terceros vendedor, o puede un revisor desestimar hallazgos que provengan de una dependencia empaquetada en lugar del código fuente propio del nodo?

Si vincula, la respuesta para este nodo es una reescritura genuina y me gustaría saberlo antes de comenzar. Si un revisor puede desestimarlo, el mismo nodo se envía con un cambio de configuración de compilación y sin riesgo para la calidad de la extracción, que es la diferencia en la que tanto tú como Nicolás estaban señalando.

En los otros dos, de acuerdo y ya hecho. El manejo de 202 y anomalías ahora es lo primero en el README, por encima de la lista de características, diciendo qué significa y qué no significa un conjunto de resultados vacío, tu formulación de “contexto para el revisor en lugar de una prueba fallida que parece un nodo roto” es exactamente por qué. Escribirlo también reveló un error real: la búsqueda de imágenes verificaba la página de anomalía en la solicitud que obtiene el token pero no en la que devuelve resultados, así que un bloqueo allí seguía regresando como una lista vacía. Arreglado, junto con la misma brecha en la ruta 403.

Aún sin noticias de nadie en n8n en el hilo. Si nada llega esta semana, tomaré las mismas tres preguntas a nodes@n8n.io e informaré aquí de cualquier forma, ya que la respuesta no es realmente específica de DuckDuckGo, cualquiera cuyo nodo necesite un analizador HTML o un cliente HTTP está frente al mismo muro.

Actualización: la versión 32.17.0 está disponible. Extract Page Content y Fetch Page Content ahora leen los primeros 2 MB de páginas grandes en lugar de fallar. El tiempo de espera de la página ahora cubre toda la descarga. La extracción se ejecuta en un hilo de trabajo, por lo que una página que es muy lenta de analizar ya no puede congelar n8n.

Dos plantillas construidas en el nodo ahora están en la biblioteca: