Kehittäjät/TypeScript SDK

Hostwolf Apps SDK JavaScriptille ja TypeScriptille

@hostwolf/apps-sdk on Hostwolf Apps -rajapinnan virallinen tyypitetty asiakaskirjasto. Sillä julkaiset ja ajat sovelluksiasi koodista: projektit, sovellukset, julkaisut ja lokit, ympäristömuuttujat, hallinnoidut tietokannat, automaattinen skaalaus, taltiot ja paljon muuta.

npm install https://app.hostwolf.net/dl/hostwolf-apps-sdk-0.2.1.tgz

SDK jaetaan osoitteesta app.hostwolf.net eikä npm-rekisteristä. Yllä oleva komento lisää sen package.json-tiedostoosi muodossa "@hostwolf/apps-sdk": "https://app.hostwolf.net/dl/hostwolf-apps-sdk-0.2.1.tgz", ja tuot sen nimellä @hostwolf/apps-sdk. pnpm, yarn ja bun hyväksyvät saman URL-osoitteen. Jokaisella versiolla on oma URL; katso Versiot.

Se toimii Node 18+:ssa, Bunissa ja Denossa, eikä sillä ole ajonaikaisia riippuvuuksia.

Pikaopas#

Luo API-tunnus konsolissa kohdassa Avaimet ja tunnukset → API-tunnukset, ja sitten:

import { HostwolfApps } from '@hostwolf/apps-sdk';

const hw = new HostwolfApps({ token: process.env.HOSTWOLF_APPS_TOKEN! });

const server = (await hw.servers.purchased()).find((s) => s.kind === 'app' && s.status === 'ready')!;
const { uuid: project } = await hw.projects.create({ name: 'shop' });

const app = await hw.applications.createFromGit({
    project_uuid: project,
    environment_name: 'production',
    server_uuid: server.server_uuid!,
    git_repository: 'https://github.com/acme/shop',
    git_branch: 'main',
    build_pack: 'nixpacks',
    ports_exposes: '3000',
});
await hw.applications.setEnvs(app.uuid, { NODE_ENV: 'production' });

const deployment = await hw.deployAndWait(app.uuid);
console.log(deployment.status, await hw.applications.logs(app.uuid, { lines: 20 }));

Resursseihin viitataan niiden uuid:llä. Vastausobjektit käyttävät rajapinnan omia kenttänimiä (snake_case), ja niiden TypeScript-tyypit viedään, esim. Application, Deployment ja ManagedDatabase.

Asetukset#

new HostwolfApps({
    token: '12|abc...',                              // required
    baseUrl: 'https://console.app.hostwolf.net',     // default
    timeoutMs: 30_000,                               // per request
    maxRetries: 2,                                   // 429s, and 502/503/504 on GET
    maxRetryWaitMs: 10_000,                          // longer Retry-After waits fail fast instead
    language: 'de',                                  // error messages in en, de, fr, es or fi
    fetch: customFetch,                              // optional
});

Projektit ja ympäristöt#

Sovellukset#

Sovellukset toimivat sovelluspalvelimillasi. server_uuid on servers.purchased()-kutsun server_uuid-kenttä (tai servers.list()-kutsun uuid). Jätä domains pois, niin saat generoidun *.app.hostwolf.net-osoitteen.

Ympäristömuuttujat#

Käynnissä olevat kontit näkevät muuttuneet muuttujat seuraavan julkaisun jälkeen.

Julkaisut#

const { deployment_uuid } = await hw.applications.deploy(app.uuid);
const done = await hw.deployments.wait(deployment_uuid!, {
    timeoutMs: 10 * 60_000,
    onStatus: (status) => console.log(status), // queued, in_progress, finished
});

wait ja deployAndWait heittävät HostwolfAppsError-virheen koodilla deployment_failed (viestissä lokin viimeiset rivit), deployment_cancelled tai timeout. Anna throwOnFailure: false, jos haluat epäonnistuneen julkaisun takaisin virheen sijaan.

Palvelimet#

Palvelimia voi ostaa ja perua vain konsolissa, joten API-tunnus ei voi koskaan ostaa palvelinta.

Usea palvelin#

Aja yhden sovelluksen kopioita usealla sovelluspalvelimellasi. Hostwolf tekee konttikuvan kerran, käynnistää kopion jokaisella palvelimella ja tasaa kuorman niiden välillä.

await hw.applications.addServer(app.uuid, otherServer.server_uuid!);
await hw.deployAndWait(app.uuid);
console.log(await hw.applications.destinations(app.uuid)); // primary + copies

removeDestination(appUuid, destinationUuid) lopettaa kopion ajamisen kyseisellä palvelimella.

Hallinnoidut tietokannat#

PostgreSQL, MySQL/MariaDB ja Redis Hostwolfin tietokantapalvelimilla, erillään sovelluspalvelimistasi, TLS:llä, öisillä varmuuskopioilla muualle ja PostgreSQL:lle ajankohtaan palautuksella.

const plans = await hw.databases.catalog();             // engines, plans, pool sizes, regions, prices
const db = await hw.databases.create({ engine: 'postgres', plan: 'small', region: 'vultr:ams' });
await hw.databases.waitUntilReady(db.uuid);
await hw.databases.attach(db.uuid, app.uuid);           // DATABASE_URL (pooled) + DATABASE_DIRECT_URL
await hw.deployAndWait(app.uuid);

Tietokanta laskutetaan tunneittain palvelintilauksellasi siitä hetkestä, kun se luodaan. create lähettää Idempotency-Key-otsakkeen, joten uudelleen yritetty kutsu ei koskaan luo toista tietokantaa; anna oma avaimesi parametrilla { idempotencyKey }.

connection(uuid) palauttaa kaksi URL-osoitetta. url kulkee yhteyspoolerin kautta (PgBouncer portissa 6432, ProxySQL portissa 6033): käytä sitä sovelluksessasi. direct_url yltää suoraan tietokantaan: käytä sitä migraatioihin, LISTEN/NOTIFY-käyttöön, istuntoasetuksiin ja pitkiin transaktioihin. Redisillä on yksi URL.

upgrade ilman parametria { confirm: true } ei muuta mitään: se heittää HostwolfAppsError-virheen koodilla confirm_required, ja error.quote sisältää uuden kuukausihinnan, joka näytetään ensin.

Automaattinen skaalaus#

const { policy, blocker, status } = await hw.autoscaling.get(app.uuid);
await hw.autoscaling.enable(app.uuid, { min_copies: 1, max_copies: 4, monthly_cap_usd: 40 });

Automaattinen skaalaus lisää sovelluspalvelimia lähelle kävijöitäsi, kun suoritinkuorma pysyy korkeana, ja poistaa ne, kun se laskee. Lisätyt palvelimet laskutetaan tunneittain normaalihintaan, enintään monthly_cap_usd asti. blocker kertoo, miksi sitä ei vielä voi ottaa käyttöön (esimerkiksi aktiivista palvelintilausta ei ole). Pois jättämäsi kentät säilyttävät arvonsa; disable(uuid) poistaa sen käytöstä. cities listaa alueiden tunnisteet, jotka allowed_cities hyväksyy sovellukselle, sekä tuntihinnan siellä; servers.regions() listaa kaikki kaupungit.

Tallennustaltiot#

Lohkotallennustilaa sovelluspalvelimillesi ja VPS:illesi: 10–1000 Gt, liitettynä palvelimella polkuun /mnt/volume-<id>, laskutus tunneittain. Laskua nostavat kutsut vaativat { confirm: true }; ilman sitä ne eivät muuta mitään ja heittävät koodin confirm_required sekä hinnan kentässä error.quote.

const offer = await hw.volumes.offer(server.uuid, { sizeGb: 50 });   // sizes allowed here and the price
const volume = await hw.volumes.create(server.uuid, { size_gb: 50, autogrow_max_gb: 200 }, { confirm: true });
await hw.volumes.waitFor(volume.id);                                  // mounted in about a minute
await hw.volumes.resize(server.uuid, volume.id, 100, { confirm: true });

Kun palvelin poistetaan, sen taltiot irrotetaan ja säilytetään 7 päivää maksutta (kept_until); liitä taltio sillä välin toiseen palvelimeen samassa kaupungissa, tai se poistetaan.

Sovellusten taltiot#

Tiimit#

Sivutus#

Rajapinnan sivuttamille listoille on kaksi tapaa: yksi metodi palauttaa yhden sivun, ja all…-metodi palauttaa asynkronisen iteraattorin jokaisen kohteen yli. collect muuttaa iteraattorin taulukoksi:

import { collect } from '@hostwolf/apps-sdk';

const deployments = await collect(hw.deployments.allForApplication(app.uuid), 100);
for await (const event of hw.teams.allAuditEvents({ action: 'deploy' })) console.log(event.description);

Virheet#

Epäonnistuneet kutsut heittävät HostwolfAppsError-virheen.

import { HostwolfAppsError } from '@hostwolf/apps-sdk';
try {
    await hw.applications.createFromDockerfile({ project_uuid, server_uuid, dockerfile });
} catch (e) {
    if (e instanceof HostwolfAppsError && e.isValidation) console.log(e.errors); // { field: ['message'] }
    else throw e;
}

Sillä on nämä ominaisuudet:

• status: HTTP-tila, tai 0 verkkovirheissä, aikakatkaisuissa ja epäonnistuneissa julkaisuissa.
• code: lyhyt koodi, kuten validation_failed, unauthenticated, forbidden, not_found, rate_limited, confirm_required, deployment_failed tai timeout.
• quote: confirm_required-virheen yhteydessä rajapinnan ilmoittama hinta (näytä se ja kutsu sitten uudelleen parametrilla { confirm: true }).
• retryAfter: 429-vastauksessa sekunnit, joiden jälkeen kutsu sallitaan taas. Lyhyet odotukset yritetään uudelleen puolestasi; pidemmät epäonnistuvat heti, ja tämä kenttä on asetettu.
• message: luettava kuvaus, kenttävirheet mukaan lukien.
• errors: 422-vastauksen kenttävirheet muodossa { field: ['message'] }.
• body: vastauksen sisältö. 403-virheessä asiasta, jonka Hostwolf tekee puolestasi (kuten palvelinten lisääminen), on mukana docs-linkki.
• Pikaliput: isNotFound, isRateLimited, isValidation, isUnauthorized ja isConfirmRequired.

Raa'at pyynnöt#

Jos päätepisteelle ei vielä ole kääremetodia, kutsu sitä suoraan:

await hw.http.get(`/applications/${uuid}/scheduled-tasks`);
await hw.http.post(`/applications/${uuid}/scheduled-tasks`, { name: 'cleanup', command: 'npm run cleanup', frequency: '0 3 * * *' });

Polut ovat suhteessa osoitteeseen /api/v1. Kaikki päätepisteet löydät API-viitteestä.

Versiot#

Päivitä asentamalla uudempi versioitu URL.

Lisenssi#

MIT