Muistettavat nimet hex-tiivisteille.

Kokeile

Tee GET-pyyntö osoitteeseen /api/v1/hash/<hex> millä tahansa hex-tiivisteellä. Päätepiste on avoin, deterministinen ja tukee CORS:ia:

Vastaus:

{
  "inputHash": "f3527e4ef32f9d8b59ead6b7b70a843c3da1c105",
  "hash": "canyon-jam-telescope-creek"
}

Miten se toimii

HumanHash muuntaa minkä tahansa heksadesimaalisen merkkijonon lyhyeksi, lausuttavaksi nimeksi kolmessa vaiheessa:

1. Jäsennä hex-syöte tavutaulukoksi.
2. Pakkaa tavut N:ään yhtä suureen segmenttiin (oletuksena N = 4) ja XOR-yhdistä kunkin segmentin tavut yhdeksi tavuksi.
3. Kuvaa jokainen tulostavu (0–255) yhdeksi sanaksi 256-sanaisesta listasta ja yhdistä sanat yhdysviivoin.

Tulos on täysin deterministinen — sama syöte tuottaa aina saman nimen — ja algoritmi on tilaton, ilman tietokantaa tai satunnaisuutta. Neljä sanaa 256-sanaisesta listasta antaa 256⁴ ≈ 4,3 miljardia yhdistelmää, mikä vastaa noin 32-bittistä sormenjälkeä: riittää yksittäisten julkaisujen tai buildien tunnistamiseen, mutta ei korvaa alkuperäistä hashia silloin, kun törmäyskestävyydellä on väliä.

API-dokumentaatio

Koodiesimerkit

curl

curl https://humanhash.dev/api/v1/hash/f3527e4ef32f9d8b59ead6b7b70a843c3da1c105

JavaScript (fetch)

const hex = "f3527e4ef32f9d8b59ead6b7b70a843c3da1c105";
const res = await fetch(`https://humanhash.dev/api/v1/hash/${hex}`);
const { hash } = await res.json();
console.log(hash); // "canyon-jam-telescope-creek"

Python

import requests

hex_digest = "f3527e4ef32f9d8b59ead6b7b70a843c3da1c105"
r = requests.get(f"https://humanhash.dev/api/v1/hash/{hex_digest}")
print(r.json()["hash"])  # "canyon-jam-telescope-creek"

Go

resp, _ := http.Get("https://humanhash.dev/api/v1/hash/f3527e4ef32f9d8b59ead6b7b70a843c3da1c105")
defer resp.Body.Close()
var out struct{ InputHash, Hash string }
json.NewDecoder(resp.Body).Decode(&out)
fmt.Println(out.Hash) // "canyon-jam-telescope-creek"

UUID

UUID:t toimivat myös — poista ensin yhdysviivat:

curl https://humanhash.dev/api/v1/hash/550e8400e29b41d4a716446655440000
# => {"inputHash":"550e8400e29b41d4a716446655440000","hash":"vault-lift-onion-lilac"}

Esimerkki: GitHub Actions

Yleinen tapa on johtaa muistettava nimi github.sha-arvosta ja käyttää sitä SHA:n rinnalla — esimerkiksi tagittamaan Docker-imagen molemmilla. Näin käytämme HumanHashia omissa tuotantoputkissamme:

name: build

on:
  push:
    branches: ["main"]

env:
  IMAGE_NAME: "ghcr.io/your-org/your-app"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get human hash
        run: echo "HUMAN_HASH=$(curl -s "https://humanhash.dev/api/v1/hash/${{ github.sha }}" | jq -r '.hash')" >> "$GITHUB_ENV"

      - name: Build Docker image
        run: docker build . --tag ${{ env.IMAGE_NAME }}:${{ github.sha }} --tag ${{ env.IMAGE_NAME }}:${{ env.HUMAN_HASH }}

      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

      - name: Push image
        run: docker push --all-tags ${{ env.IMAGE_NAME }}

Jokainen push saa kaksi tagia: tarkan SHA:n toistettavuutta varten ja ihmisystävällisen nimen, kuten swift-river-mellow-bolt — se on aidosti käyttökelpoinen chatissä, kojelaudoissa ja palavereissa. Komento jq on esiasennettu GitHubin ubuntu-latest-runnerille, joten lisäasennuksia ei tarvita.

Käyttötapaukset

• Build- ja deploy-nimet. Tagita CI-build nimellä swift-river-mellow-bolt eikä 7c4f9a2. Helpompi viitata siihen palavereissa ja löytää chat-historiasta.
• Commit-viittaukset chatissä. Slackiin liitetty SHA jää huomaamatta; canyon-jam-telescope-creek tulee luetuksi.
• Sessio- ja request-ID:t logeissa. Kun grepit logeja useammasta palvelusta tai sanot ID:n ääneen puhelussa, sanat voittavat hex-merkkijonon.
• Varmuuskopio- ja snapshot-nimet. Nimen vault-bronze-falcon-river palauttaminen pelottaa vähemmän kuin nimen b8f9c1d2… palauttaminen.
• Sormenjälkien vertailu. SSH- tai TLS-sormenjälkien silmämääräinen vertailu on paljon nopeampaa neljänä sanana kuin 40 hex-merkkinä.
• Asset- ja versionimet. Anna build-artefakteille, mallien checkpointeille tai data-snapshoteille nimi, josta ihmiset voivat puhua.

Vertailu muihin tunnistemuotoihin

HumanHashin erikoisuus on, että se on deterministinen projektio olemassa olevasta tunnisteesta — se ei korvaa UUID:tä tai hashia, vaan antaa sille rinnalle nimen, jonka ihminen pystyy lukemaan. Käytä molempia yhdessä.

Usein kysytyt kysymykset

256-sanainen sanasto

Tulokset poimitaan käsin kuratoidusta listasta, jossa on 256 lyhyttä ja helposti lausuttavaa englanninkielistä sanaa, jaettuna kahdeksaan teemaryhmään — kussakin 32 sanaa. Lista välttää epäselviä kirjoitusasuja, lähihomofoneja ja sanoja, jotka luetaan huonosti ketjutettuina.

Tietoa

HumanHashia ylläpitää Pilvia Oy, suomalainen pilviyritys. Käytämme sitä sisäisesti buildien, julkaisujen ja snapshotien merkitsemiseen, ja olemme avanneet sen, koska algoritmi on yleishyödyllinen.

Alkuperäinen humanhash-konsepti syntyi Zachary Voasen pienestä Python-kirjastosta. Tämä toteutus on itsenäinen TypeScript-uudelleenkirjoitus Cloudflare Workersilla, omalla räätälöidyllä sanastolla.