Vanity Imports

Llevamos ya un tiempo sin publicar artículos y es que en el verano nos han pasado muchas cosas que nos han complicado la publicación de los mismos. Pero ya estamos de vuelta, con nuevas energías para continuar el año.

Hoy os queremos traer un artículo para que evolucionéis vuestros proyectos Go, un poco más y les deis mucha más seriedad.

¿Qué son los Vanity Imports?

Durante el transcurso de un proyecto en Go es normal tener que importar multitud de paquetes, y si os habéis fijado muchos empiezan por github.com, ya que el modulo de nuestros paquetes coincidirá con la url a la que tiene que ir a buscarlo para descargarlo; pero si hacéis memoria estoy seguro que habréis visto otros tantos pacakge que no tienen su url de github, como por ejemplo:

• go.mongodb.org/mongo-driver/mongo
• contrib.go.opencensus.io/exporter/jaeger
• gocloud.dev/docstore

Seguro que ahora estaréis pensando que esto sólo puede ser hecho por grandes empresas o con un proceso súper complicado, ya nada más lejos de la realidad, ya que Go tiene un mecanismo para realizar imports customizados o vanity import paths.

¿Qué ventajas y desventajas tiene un Vanity Import?

Ahora que ya sabes que es posible tener tu propia url como import path, te estarás preguntando que ventajas ofrece esto, a parte de molonidad.

Lo que nos permiten los vanity imports a través de su mecanismo es una forma de tener descentralizado nuestro package, es decir pongamos de ejemplo una de nuestras últimas librerías (aún en working in progress), github.com/friendsofgo/gocache, si quisierais utilizar esa dicha librería en vuestros proyectos, tendríais que realizar el import pertinente:

import github.com/friendsofgo/gocache

Y go modules se encargaría de lo demás.

Y hasta ahí todo perfecto, pero es que esto tiene un gran problema, estamos acoplados a github.

A simple vista esto puede no pareceros demasiado importante, pero pensad que en Go ésta es la ruta del paquete que queremos importar, es decir si esa ruta cambia, tendremos un breaking change en todos los proyectos que utilicemos dicha librería.

Y es ahí donde entra el vanity import ya que mediante su configuración como veremos en breve, podremos decidir donde estará alojado nuestro código con una misma ruta siempre.

Es decir, una vez tenga configurado mi vanity import, por ejemplo, pkg.friendsofgo.tech/gocache, dará igual si mi código lo muevo de github a gitlab, a bitbucket o a un servidor en los alpes, para los usuarios finales será transparente.

Pero no es oro todo lo que reluce, y es que esto también tiene sus problematicas a ser:

• ¿Qué pasa si perdemos el control sobre el dominio?
• ¿Qué pasa si cambiamos la configuración de por ejemplo el DNS?
• ¿Qué pasa si el servidor web donde está alojado el vanity import cae?

Son dudas que nos pueden surgir, al utilizar o crear un vanity import, pero os pregunto yo ahora, ¿Github nunca se ha caído?, ¿no pueden borrar un repositorio o cambiarle el nombre, ejem logrush.

Es decir de cualquier manera estamos expuestos a que de repente nuestro código se vea afectado por terceros de alguna manera, a no ser claro está que realicemos vendoring.

Igualmente en la comunidad, está muy bien visto utilizar vanity imports porque demuestra que no es un proyecto creado para jugar, sino que manda un mensaje claro de que te preocupa lo que estás desarrollando.

¿Te he convencido? ¡Hagamos nuestro vanity import!

Lo primero que tendremos que hacer es elegir un import path para ello podemos fijarnos en otras librerías y ver como lo han hecho, pero en resumidas cuentas tenemos 3 formas, que demás se pueden combinar.

• dominio base, por ejemeplo, friendsofgo.tech/{pkg_name}.
• subdominio, por ejemplo, pkg.friendsofgo.tech/{pkg_name}.
• utlizar cualquiera de las anteriores más un path, es decir, friendsofgo.tech/pkg/{pkg_name}

Para la elección del dominio sino tienes uno ya como es nuestro caso, se recomienda usar, .dev o .io ya que son representativos de desarrollo, además en Go a la hora de elegir un subdominio, muchos eligen go. ya que así queda clara la intención, como es el caso de, mongo, go.mongodb.org, o uber, go.uber.org. En nuestro caso hemos escogido, pkg. ya que también es muy claro dentro de la comunidad Go y utilizar go. sobre friendsofgo quedaba muy redundante.

Otra recomendación es que siempre que puedas utilices, HTTPS, el comando go lo soporta sin problemas y hoy en día hay formas para tenerlo a 0 coste, como Let's Encrypt o directamente utilizando hosting de páginas estáticas como es el caso de Netlify (dónde nosotros tenemos alojado el nuestro) o Github Pages.

Ahora que ya hemos decidido el nombre de nuestro import, en nuestro caso será pkg.friendsofgo.tech nos toca configurar nuestro site, para ello necesitaremos simplemente conocimientos muy básicos de HTML o de copy and paste (éste último es una técnica milenaria conocida por los mejores developers del mundo).

Lo primero que haremos es configurar nuestro root page es decir que pasá si alguien accede a pkg.friendsofgo.tech ¿qué verá?, aquí podéis poneros muy creativos o hacer como nosotros:

<!-- index.html -->

<!DOCTYPE html>
<html>
<h1>pkg.friendsofgo.tech</h1>
<ul>
    <li><a href="https://pkg.go.dev/pkg.friendsofgo.tech/gocache">pkg.friendsofgo.tech/gocache</a></li>   
</ul>
</html>

Ya os digo, podéis poneros creativos incluso añadir unicornios, los unicornios 🦄 siempre van bien, pero nosotros hemos optado por poner un listado de los repositorios que tenemos configurados.

Lo siguiente será preparar el index.html de nuestro repositorio, en este caso gocache, así que crearemos un directorio con dicho nombre y dentro su index.html.

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <meta name="go-import" content="pkg.friendsofgo.tech/gocache git https://github.com/friendsofgo/gocache">
    <meta name="go-source" content="pkg.friendsofgo.tech/gocache https://github.com/friendsofgo/gocache https://github.com/friendsofgo/gocache/tree/master{/dir} https://github.com/friendsofgo/gocache/blob/master{/dir}/{file}#L{line}">
</head>
<body>
Nothing to see here; <a href="https://pkg.go.dev/pkg.friendsofgo.tech/gocache/">see the package on pkg.go.dev</a>.
</body>
</html>

En este caso también hemos decidido centrarnos en el minimalismo, pero vamos a explicar por parte que hacen las etiquetas meta que hemos declarado.

Cuando utilizamos el comando go get para obtener una librería, este lo que hace es descargarse la información que obtiene en dicha url, para ello lee las cabeceras de dicha página y recoge la información que necesita.

La etiqueta obligatorio para ello es go-import que es la que le informará de como tiene que acceder a dicho control de verisones.

<meta name="go-import" content="import-prefix vcs repo-root">

lo que podemos traducir a:

<meta name="go-import" content="pkg.friendsofgo.tech/gocache git https://github.com/friendsofgo/gocache">

Opcionalmente podemos añadir la etiqueta de meta go-source, que lo que hará es ofrecer los links necesarios al godoc, como podemos ver quedaría así:

<meta name="go-source" content="pkg.friendsofgo.tech/gocache 
https://github.com/friendsofgo/gocache 
https://github.com/friendsofgo/gocache/tree/master{/dir} 
https://github.com/friendsofgo/gocache/blob/master{/dir}/{file}#L{line}">

El html restante lo que hace es llevarnos a la página de nuestro repositorio en la nueva página de paquetes de Go, pkg.go.dev.

Tips

Ya sabemos como montar nuestro vanity import, pero hay algunos tips que os puedo dar para ayudaros en algunos casos, por ejemplo, si utilizamos nuestro dominio personal, para nuestra propia página web y además queremos utilizarlo como vanity import.

Para ello tenéis que saber que cuando se llama a una url desde el comando go get, se manda el query string, go-get=1, así que podremos crear configuraciones en base a eso para entregar un contenido u otro.

Además existen generadores de vanity imports como vangen, dicha tool se encargará de generar tu vanity import el cual tendrás que subir a un servidor web.

Conclusión

Ya sabemos como crear nuestros vanity imports para añadir esa profesionalidad a nuestras librerías e informar al mundo de que vamos enserio con nuestro proyecto.

Recordar que si tenéis alguna duda o comentario podéis dejarla aquí mismo o a través de nuestro Twitter FriendsOfGoTech.