├── .eslintrc.json ├── .gitignore ├── .prettierignore ├── README.md ├── bun.lockb ├── check-links ├── check-links.ts └── markdown-link-extractor.d.ts ├── lefthook.yml ├── next.config.js ├── openapi ├── cloud-spec.yaml ├── gen-openapi.ts └── oss-spec.yaml ├── package-lock.json ├── package.json ├── postcss.config.js ├── prettier.config.js ├── public ├── favicon.ico ├── icon.svg └── images │ ├── create-new-api.png │ ├── project-apis-link.png │ └── projects-link.png ├── rib-grammar.json ├── src ├── components │ ├── all-wit-deps.tsx │ ├── app-manifest-schema.tsx │ ├── footer.tsx │ ├── golem-logo.tsx │ └── multi-platform-command.tsx ├── pages │ ├── 404.mdx │ ├── _app.tsx │ ├── _document.tsx │ ├── _meta.json │ ├── app-manifest.mdx │ ├── ccpp-language-guide │ │ ├── _meta.json │ │ ├── building-components.mdx │ │ ├── defining-components.mdx │ │ ├── durability.mdx │ │ ├── http.mdx │ │ ├── next-steps.mdx │ │ ├── promises.mdx │ │ ├── retries.mdx │ │ ├── setup.mdx │ │ ├── updating.mdx │ │ └── wasi.mdx │ ├── cli.mdx │ ├── cli │ │ ├── _meta.json │ │ ├── app-manifest.mdx │ │ ├── components.mdx │ │ ├── install-from-source.mdx │ │ ├── permissions.mdx │ │ ├── plugins.mdx │ │ ├── profiles.mdx │ │ ├── shell-completion.mdx │ │ └── workers.mdx │ ├── common-language-guide │ │ ├── _meta.json │ │ ├── forking.mdx │ │ ├── llm.mdx │ │ ├── rdbms.mdx │ │ ├── rpc.mdx │ │ ├── shared-wit-packages.mdx │ │ ├── wasi-http.mdx │ │ └── worker-filesystem.mdx │ ├── concepts.mdx │ ├── concepts │ │ ├── _meta.json │ │ ├── api-definitions.mdx │ │ ├── components.mdx │ │ ├── invocations.mdx │ │ ├── plugins.mdx │ │ ├── reliability.mdx │ │ ├── worker-gateway.mdx │ │ ├── worker-to-worker-communication.mdx │ │ └── workers.mdx │ ├── debug.mdx │ ├── deploy.mdx │ ├── deploy │ │ ├── _meta.json │ │ ├── docker.mdx │ │ ├── golem-cloud.mdx │ │ └── kubernetes.mdx │ ├── desktop.mdx │ ├── develop-overview.mdx │ ├── experimental-languages │ │ ├── _meta.json │ │ ├── moonbit-language-guide │ │ │ ├── _meta.json │ │ │ ├── building-components.mdx │ │ │ ├── defining-components.mdx │ │ │ ├── next-steps.mdx │ │ │ └── setup.mdx │ │ ├── scalajs-language-guide │ │ │ ├── _meta.json │ │ │ ├── building-components.mdx │ │ │ ├── defining-components.mdx │ │ │ ├── next-steps.mdx │ │ │ └── setup.mdx │ │ └── zig-language-guide │ │ │ ├── _meta.json │ │ │ ├── building-components.mdx │ │ │ ├── defining-components.mdx │ │ │ ├── next-steps.mdx │ │ │ └── setup.mdx │ ├── function-names.mdx │ ├── fundamentals.mdx │ ├── go-language-guide │ │ ├── _meta.json │ │ ├── building-components.mdx │ │ ├── defining-components.mdx │ │ ├── durability.mdx │ │ ├── golem-go-sdk.mdx │ │ ├── http.mdx │ │ ├── next-steps.mdx │ │ ├── promises.mdx │ │ ├── retries.mdx │ │ ├── setup.mdx │ │ ├── transactions.mdx │ │ ├── updating.mdx │ │ ├── wasi.mdx │ │ └── worker-metadata.mdx │ ├── golem-host-functions.mdx │ ├── http-api-definitions.mdx │ ├── http-api-definitions │ │ └── api-definition-bindings.mdx │ ├── index.mdx │ ├── installing-webassembly-tooling.mdx │ ├── invoke.mdx │ ├── invoke │ │ ├── _meta.json │ │ ├── cli.mdx │ │ ├── http.mdx │ │ ├── making-custom-apis.mdx │ │ ├── making-custom-apis │ │ │ ├── _meta.json │ │ │ ├── authentication.mdx │ │ │ ├── component-constraints.mdx │ │ │ ├── cors.mdx │ │ │ ├── create-simple-component.mdx │ │ │ ├── expose-http-apis.mdx │ │ │ ├── external-api-gateways.mdx │ │ │ ├── import-openapi-spec.mdx │ │ │ ├── rib-in-api-definition.mdx │ │ │ ├── spec-inference.mdx │ │ │ ├── trouble-shooting.mdx │ │ │ ├── try-out-deployed-api.mdx │ │ │ └── update-api-deployment.mdx │ │ └── repl.mdx │ ├── js-language-guide │ │ ├── _meta.json │ │ ├── building-components.mdx │ │ ├── defining-components.mdx │ │ ├── durability.mdx │ │ ├── golem-js-sdk.mdx │ │ ├── http.mdx │ │ ├── next-steps.mdx │ │ ├── promises.mdx │ │ ├── retries.mdx │ │ ├── setup.mdx │ │ ├── transactions.mdx │ │ ├── updating.mdx │ │ └── wasi.mdx │ ├── json-wave-mapping.mdx │ ├── operate │ │ ├── _meta.json │ │ ├── invocation_context.mdx │ │ ├── logs.mdx │ │ ├── metadata.mdx │ │ ├── metrics.mdx │ │ └── persistence.mdx │ ├── python-language-guide │ │ ├── _meta.json │ │ ├── building-components.mdx │ │ ├── defining-components.mdx │ │ ├── durability.mdx │ │ ├── http.mdx │ │ ├── next-steps.mdx │ │ ├── promises.mdx │ │ ├── retries.mdx │ │ ├── setup.mdx │ │ ├── updating.mdx │ │ └── wasi.mdx │ ├── quickstart.mdx │ ├── rest-api.mdx │ ├── rest-api │ │ ├── _meta.json │ │ ├── cloud-rest-api.mdx │ │ ├── cloud-rest-api │ │ │ ├── account.mdx │ │ │ ├── api-certificate.mdx │ │ │ ├── api-definition.mdx │ │ │ ├── api-deployment.mdx │ │ │ ├── api-domain.mdx │ │ │ ├── api-security.mdx │ │ │ ├── component.mdx │ │ │ ├── limits.mdx │ │ │ ├── login.mdx │ │ │ ├── plugin.mdx │ │ │ ├── project-grant.mdx │ │ │ ├── project-policy.mdx │ │ │ ├── project.mdx │ │ │ ├── token.mdx │ │ │ └── worker.mdx │ │ ├── oss-rest-api.mdx │ │ └── oss-rest-api │ │ │ ├── api-definition.mdx │ │ │ ├── api-deployment.mdx │ │ │ ├── api-security.mdx │ │ │ ├── component.mdx │ │ │ ├── plugin.mdx │ │ │ └── worker.mdx │ ├── rib.mdx │ ├── rust-language-guide │ │ ├── _meta.json │ │ ├── building-components.mdx │ │ ├── defining-components.mdx │ │ ├── durability.mdx │ │ ├── http.mdx │ │ ├── next-steps.mdx │ │ ├── promises.mdx │ │ ├── retries.mdx │ │ ├── setup.mdx │ │ ├── transactions.mdx │ │ ├── updating.mdx │ │ └── wasi.mdx │ ├── ts-language-guide │ │ ├── _meta.json │ │ ├── building-components.mdx │ │ ├── defining-components.mdx │ │ ├── durability.mdx │ │ ├── golem-ts-sdk.mdx │ │ ├── http.mdx │ │ ├── next-steps.mdx │ │ ├── promises.mdx │ │ ├── retries.mdx │ │ ├── setup.mdx │ │ ├── transactions.mdx │ │ ├── updating.mdx │ │ └── wasi.mdx │ ├── wasm-rpc.mdx │ └── why-golem.mdx └── styles │ └── globals.css ├── tailwind.config.ts ├── theme.config.tsx ├── tsconfig.json └── wit-grammar.json /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "next/core-web-vitals" 3 | } 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 2 | 3 | 4 | .idea/ 5 | 6 | # dependencies 7 | /node_modules 8 | /.pnp 9 | .pnp.js 10 | .yarn/install-state.gz 11 | 12 | # testing 13 | /coverage 14 | 15 | # next.js 16 | /.next/ 17 | /out/ 18 | 19 | # production 20 | /build 21 | 22 | # misc 23 | .DS_Store 24 | *.pem 25 | 26 | # debug 27 | npm-debug.log* 28 | yarn-debug.log* 29 | yarn-error.log* 30 | 31 | # local env files 32 | .env*.local 33 | 34 | # vercel 35 | .vercel 36 | 37 | # typescript 38 | *.tsbuildinfo 39 | next-env.d.ts 40 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | *.mdx -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Getting Started 2 | 3 | 1. [Install Bun](https://bun.sh/docs/installation) 4 | 2. Install dependencies 5 | 6 | `bun install` 7 | 8 | 3. Run the development server 9 | 10 | `bun run dev` 11 | 12 | 4. Open http://localhost:3001 with your browser to see the result. 13 | 14 | ## Developing Guide 15 | 16 | This docs site is built with [Nextra](https://nextra.site/) 17 | 18 | ## Adding a new page 19 | 20 | Each docs page is created from a .mdx file. To add a new page, create a new .mdx file in the `pages` directory. The file name will be the URL path. 21 | 22 | For example, `pages/docs/getting-started.mdx` will be available at `/docs/getting-started`. 23 | 24 | ### Changing page metadata 25 | 26 | In order to change the page's title or placement on the left hand sidebar, you need to create a `_meta.json` file in the same directory as the .mdx file. 27 | 28 | [Read more about Nextra's \_meta.json files](https://nextra.site/docs/guide/organize-files#_metajson). 29 | 30 | [Read more about Nextra's docs theme](https://nextra.site/docs/docs-theme). 31 | 32 | If we had a page `/pages/docs/getting-started.mdx`, we could add a `_meta.json` file to change the title and make it the first entry in the sidebar. 33 | 34 | ```json 35 | { 36 | "getting-started": { 37 | "title": "Getting Started - Overview" 38 | }, 39 | "other-page": "Other Page" 40 | } 41 | ``` 42 | 43 | Note how the key in the json object matches the file name. This is how Nextra knows which page to apply the metadata to. 44 | 45 | > If the value is a json object, you can set multiple parameters. If it's a string, it will just change the title. 46 | -------------------------------------------------------------------------------- /bun.lockb: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golemcloud/docs/8a843f60182239fa9f97837b320d738eba316e65/bun.lockb -------------------------------------------------------------------------------- /check-links/markdown-link-extractor.d.ts: -------------------------------------------------------------------------------- 1 | declare module "markdown-link-extractor" { 2 | export default function markdownLinkExtractor(markdown: string): string[] 3 | } 4 | -------------------------------------------------------------------------------- /lefthook.yml: -------------------------------------------------------------------------------- 1 | lint_glob: &lint_glob "*.{js,jsx,ts,tsx,cjs,mjs}" 2 | prettier_glob: &prettier_glob "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc,md,mdx}" 3 | 4 | pre-commit: 5 | parallel: false 6 | commands: 7 | lint: 8 | glob: *lint_glob 9 | run: bunx eslint --fix {staged_files} 10 | lint-add: 11 | glob: *lint_glob 12 | run: git add {staged_files} 13 | prettier: 14 | glob: *prettier_glob 15 | run: bunx prettier --log-level warn --write {staged_files} 16 | prettier-add: 17 | glob: *prettier_glob 18 | run: git add {staged_files} 19 | typecheck: 20 | run: bunx tsc 21 | check-links: 22 | run: bun run check-links {staged_files} 23 | 24 | pre-build: 25 | parallel: true 26 | commands: 27 | lint: 28 | glob: *lint_glob 29 | run: bunx eslint {all_files} 30 | prettier: 31 | glob: *prettier_glob 32 | run: bunx prettier --log-level warn --check {all_files} 33 | typecheck: 34 | run: bunx tsc 35 | check-links: 36 | run: bun run check-links {all_files} 37 | 38 | fix: 39 | parallel: false 40 | commands: 41 | lint: 42 | glob: *lint_glob 43 | run: next lint --fix . 44 | prettier: 45 | glob: *prettier_glob 46 | run: bunx prettier --log-level silent --write ./src -------------------------------------------------------------------------------- /next.config.js: -------------------------------------------------------------------------------- 1 | const shiki = require("shiki") 2 | const nextra = require("nextra") 3 | 4 | const withNextra = nextra({ 5 | theme: "nextra-theme-docs", 6 | themeConfig: "./theme.config.tsx", 7 | mdxOptions: { 8 | rehypePrettyCodeOptions: { 9 | getHighlighter: options => 10 | shiki.getHighlighter({ 11 | ...options, 12 | langs: [ 13 | ...shiki.BUNDLED_LANGUAGES, 14 | { 15 | id: "wit", 16 | scopeName: "source.wit", 17 | aliases: [""], // Along with id, aliases will be included in the allowed names you can use when writing markdown. 18 | // this is relative path from node_modules/shiki/index.js 19 | path: "../../wit-grammar.json", 20 | }, 21 | { 22 | id: "rib", 23 | scopeName: "source.rib", 24 | aliases: [""], // Along with id, aliases will be included in the allowed names you can use when writing markdown. 25 | // this is relative path from node_modules/shiki/index.js 26 | path: "../../rib-grammar.json", 27 | }, 28 | ], 29 | }), 30 | }, 31 | }, 32 | }) 33 | 34 | module.exports = withNextra({ 35 | reactStrictMode: true, 36 | experimental: { 37 | scrollRestoration: true, 38 | }, 39 | }) 40 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "golem-docs", 3 | "version": "0.1.0", 4 | "private": true, 5 | "scripts": { 6 | "postinstall": "lefthook install", 7 | "dev": "next dev", 8 | "build:check": "lefthook run pre-build", 9 | "build": "next build", 10 | "start": "next start", 11 | "lint": "next lint --fix", 12 | "format": "prettier --log-level silent --write ./src", 13 | "check-links": "bun ./check-links/check-links.ts", 14 | "fix": "concurrently -m 1 'npm run lint' 'npm run format'", 15 | "generate-local": "concurrently -m 1 'bun run openapi/gen-openapi.ts --local' 'bun run fix'", 16 | "generate-dev": "concurrently -m 1 'bun run openapi/gen-openapi.ts --dev' 'bun run fix'", 17 | "generate-prod": "concurrently -m 1 'bun run openapi/gen-openapi.ts --prod' 'bun run fix'" 18 | }, 19 | "dependencies": { 20 | "@radix-ui/react-icons": "^1.3.0", 21 | "lucide-react": "^0.412.0", 22 | "next": "14.0.0", 23 | "nextra": "^2.13.2", 24 | "nextra-theme-docs": "^2.13.2", 25 | "react": "^18", 26 | "react-dom": "^18", 27 | "shiki": "^0.14.3" 28 | }, 29 | "devDependencies": { 30 | "@apidevtools/swagger-parser": "^10.1.0", 31 | "@types/bun": "^1.0.1", 32 | "@types/node": "^20", 33 | "@types/react": "^18", 34 | "@types/react-dom": "^18", 35 | "autoprefixer": "^10", 36 | "concurrently": "^8.2.2", 37 | "eslint": "^8", 38 | "eslint-config-next": "14.0.0", 39 | "glob": "^11.0.0", 40 | "lefthook": "^1.6.1", 41 | "markdown-link-extractor": "^4.0.2", 42 | "openapi-sampler": "^1.4.0", 43 | "openapi-types": "^12.1.3", 44 | "postcss": "^8", 45 | "prettier": "^3.4.2", 46 | "prettier-plugin-tailwindcss": "^0.6.11", 47 | "tailwindcss": "^3", 48 | "typescript": "^5" 49 | } 50 | } 51 | -------------------------------------------------------------------------------- /postcss.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | plugins: { 3 | tailwindcss: {}, 4 | autoprefixer: {}, 5 | }, 6 | } 7 | -------------------------------------------------------------------------------- /prettier.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | plugins: ["prettier-plugin-tailwindcss"], 3 | trailingComma: "es5", 4 | tabWidth: 2, 5 | semi: false, 6 | singleQuote: false, 7 | printWidth: 100, 8 | arrowParens: "avoid", 9 | jsxSingleQuote: false, 10 | } 11 | -------------------------------------------------------------------------------- /public/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golemcloud/docs/8a843f60182239fa9f97837b320d738eba316e65/public/favicon.ico -------------------------------------------------------------------------------- /public/images/create-new-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golemcloud/docs/8a843f60182239fa9f97837b320d738eba316e65/public/images/create-new-api.png -------------------------------------------------------------------------------- /public/images/project-apis-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golemcloud/docs/8a843f60182239fa9f97837b320d738eba316e65/public/images/project-apis-link.png -------------------------------------------------------------------------------- /public/images/projects-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golemcloud/docs/8a843f60182239fa9f97837b320d738eba316e65/public/images/projects-link.png -------------------------------------------------------------------------------- /rib-grammar.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json", 3 | "name": "Rib", 4 | "scopeName": "source.rib", 5 | "patterns": [ 6 | { "include": "#keywords" }, 7 | { "include": "#operators" }, 8 | { "include": "#literals" }, 9 | { "include": "#types" }, 10 | { "include": "#identifiers" } 11 | ], 12 | "repository": { 13 | "keywords": { 14 | "patterns": [ 15 | { 16 | "match": "\\b(let|if|then|else|for|in|yield|reduce|from|some|none|ok|error|instance)\\b", 17 | "name": "keyword.control.rib" 18 | } 19 | ] 20 | }, 21 | "operators": { 22 | "patterns": [ 23 | { "match": "\\b(>=|<=|==|<|>|&&|\\|\\||\\+|\\-|\\*|/)\\b", "name": "keyword.operator.rib" }, 24 | { "match": "\\.{2,3}=?", "name": "keyword.operator.range.rib" } 25 | ] 26 | }, 27 | "literals": { 28 | "patterns": [ 29 | { "match": "\\b(true|false)\\b", "name": "constant.language.boolean.rib" }, 30 | { "match": "\\d+", "name": "constant.numeric.rib" }, 31 | { "match": "\"(\\\\.|[^\"])*\"", "name": "string.quoted.double.rib" } 32 | ] 33 | }, 34 | "types": { 35 | "patterns": [ 36 | { 37 | "match": "\\b(bool|s8|u8|s16|u16|s32|u32|s64|u64|f32|f64|char|string|list|tuple|option|result)\\b", 38 | "name": "storage.type.rib" 39 | } 40 | ] 41 | }, 42 | "identifiers": { 43 | "patterns": [{ "match": "[a-zA-Z_][a-zA-Z0-9_-]*", "name": "variable.rib" }] 44 | } 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /src/components/multi-platform-command.tsx: -------------------------------------------------------------------------------- 1 | import { Code, Pre, Tabs } from "nextra/components" 2 | import { Fragment } from "react" 3 | import { ComponentProps } from "react" 4 | 5 | type Props = { 6 | commands: Command[] 7 | language?: string 8 | } & Omit, "children"> 9 | 10 | type Command = { 11 | label: string 12 | command: string 13 | } 14 | 15 | export const MultiPlatformCommand = ({ commands: command, language, ...props }: Props) => { 16 | const labels = command.map(c => c.label) 17 | 18 | // Mimicking the shiki theme 19 | const commands = command.map(c => 20 | c.command.split("\n").map((line, i) => { 21 | const lines = line.split(" ") 22 | return ( 23 | 24 | {lines.map((word, i) => ( 25 | 26 | {i === 0 ? ( 27 | {word} 28 | ) : ( 29 | {word} 30 | )} 31 | {i < lines.length - 1 && } 32 | 33 | ))} 34 | 35 | ) 36 | }) 37 | ) 38 | 39 | return ( 40 | 41 | {commands.map((cmd, i) => ( 42 | 43 | 
49 |             {cmd}
50 |
51 | 52 | ))} 53 | 54 | ) 55 | } 56 | -------------------------------------------------------------------------------- /src/pages/404.mdx: -------------------------------------------------------------------------------- 1 | # Page Not Found 2 | -------------------------------------------------------------------------------- /src/pages/_app.tsx: -------------------------------------------------------------------------------- 1 | import "../styles/globals.css" 2 | 3 | import type { AppProps } from "next/app" 4 | 5 | import { Inter } from "next/font/google" 6 | 7 | const font = Inter({ 8 | subsets: ["latin"], 9 | display: "swap", 10 | variable: "--font-sans", 11 | }) 12 | 13 | export default function MyApp({ Component, pageProps }: AppProps) { 14 | return ( 15 |
22 | 23 |
24 | ) 25 | } 26 | -------------------------------------------------------------------------------- /src/pages/_document.tsx: -------------------------------------------------------------------------------- 1 | import { Html, Head, Main, NextScript } from "next/document" 2 | 3 | export default function Document() { 4 | return ( 5 | 6 | 7 | 8 |
9 | 10 | 11 | 12 | ) 13 | } 14 | -------------------------------------------------------------------------------- /src/pages/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Home", 3 | "-- Getting Started": { 4 | "type": "separator", 5 | "title": "Getting Started" 6 | }, 7 | "why-golem": "Why Golem?", 8 | "fundamentals": "Fundamentals", 9 | "quickstart": "Quickstart", 10 | "concepts": { 11 | "title": "Concepts" 12 | }, 13 | "-- Develop": { 14 | "type": "separator", 15 | "title": "Develop" 16 | }, 17 | "develop-overview": "Language Guides", 18 | "rust-language-guide": "Rust Language Guide", 19 | "ccpp-language-guide": "C/C++ Language Guide", 20 | "python-language-guide": "Python Language Guide", 21 | "go-language-guide": "Go Language Guide", 22 | "js-language-guide": "JavaScript Language Guide", 23 | "ts-language-guide": "TypeScript Language Guide", 24 | "experimental-languages": "Experimental Languages", 25 | "common-language-guide": "Common Guides", 26 | "-- Usage": { 27 | "type": "separator", 28 | "title": "Usage" 29 | }, 30 | "deploy": { 31 | "title": "Deploy" 32 | }, 33 | "invoke": { 34 | "title": "Invoke" 35 | }, 36 | "debug": { 37 | "title": "Debug" 38 | }, 39 | "operate": { 40 | "title": "Operate" 41 | }, 42 | "cli": { 43 | "title": "CLI" 44 | }, 45 | "desktop": { 46 | "title": "Desktop" 47 | }, 48 | "-- References": { 49 | "type": "separator", 50 | "title": "References" 51 | }, 52 | "http-api-definitions": "API Definitions", 53 | "app-manifest": "Application Manifest", 54 | "function-names": "Function names", 55 | "golem-host-functions": "Golem Host Functions", 56 | "installing-webassembly-tooling": "Installing WebAssembly Tooling", 57 | "json-wave-mapping": "JSON-WAVE Mapping", 58 | "rest-api": "REST API", 59 | "rib": "Rib", 60 | "wasm-rpc": "WASM RPC" 61 | } 62 | -------------------------------------------------------------------------------- /src/pages/ccpp-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps", 10 | "-- golem-sdk": { 11 | "type": "separator", 12 | "title": "Golem SDK" 13 | }, 14 | "http": "HTTP client", 15 | "durability": "Durability", 16 | "retries": "Retries", 17 | "promises": "Promises", 18 | "updating": "Updating Workers", 19 | "wasi": "WASI" 20 | } 21 | -------------------------------------------------------------------------------- /src/pages/ccpp-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in C 5 | 6 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 7 | 8 | ```shell copy 9 | golem app build 10 | ``` 11 | 12 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 13 | 14 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 15 | 16 | ```shell copy 17 | golem component add 18 | ``` 19 | 20 | ## Under the hood 21 | Under the hood, building Golem components written in C involves a few steps. 22 | 23 | In details, building the component requires the following steps: 24 | 25 | 26 | ### Generate the C bindings from the WIT files 27 | 28 | ```shell 29 | $ wit-bindgen c --autodrop-borrows yes ./wit 30 | Generating "example.c" 31 | Generating "example.h" 32 | Generating "example_component_type.o" 33 | ``` 34 | 35 | ### Compile the C code 36 | 37 | Include all your source files and additionally the generated `.c` and `.o` files and use the `clang` provided as part of the WASM SDK: 38 | 39 | ```shell 40 | $ $WASI_SDK_PATH/bin/clang --sysroot $WASI_SDK_PATH/share/wasi-sysroot main.c example.c example_component_type.o -o example.module.wasm 41 | ``` 42 | 43 | ### Package it into a WASM component 44 | 45 | The resulting `example.module.wasm` is a WebAssembly module, not a component. To be able to use it as a **Golem component**, use `wasm-tools` to package the module as a component: 46 | 47 | ```shell 48 | $ wasm-tools component new example.module.wasm -o example.wasm --adapt adapters/tier1/wasi_snapshot_preview1.wasm 49 | ``` 50 | 51 | 52 | Note that the `adapters/tier1/wasi_snapshot_preview1.wasm` file is placed in the project's directory when using `golem new` to create the new project. 53 | 54 | If needed, it can be manually downloaded from https://github.com/golemcloud/golem-wit/blob/main/adapters/tier1/wasi_snapshot_preview1.wasm 55 | 56 | 57 | 58 | 59 | -------------------------------------------------------------------------------- /src/pages/ccpp-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the C development environment](/ccpp-language-guide/setup) and learning the basic steps [writing a Golem component](/ccpp-language-guide/defining-components) and [building them](/ccpp-language-guide/building-components), please consider learning about the following topics: 6 | 7 | 8 | ### Making HTTP requests from a Golem component 9 | Learn how to [send HTTP requests from a Golem component written in C/C++](/docs/ccpp-language-guide/http). 10 | 11 | ### Control durability guarantees 12 | 13 | Check how the Golem runtime API can [control various durability settings](/ccpp-language-guide/durability) of Golem. 14 | 15 | ### Automatic retries 16 | 17 | Learn about Golem's retry mechanism and [how it can be customized](/ccpp-language-guide/retries). 18 | 19 | ### Promises 20 | 21 | Create and use [promises](/ccpp-language-guide/promises) to await external events from within a running worker. 22 | 23 | ### Using WASI interfaces 24 | 25 | See what low-level [WASI interfaces](/ccpp-language-guide/wasi) are available and how they can be used from C/C++. 26 | 27 | ### Call other workers from a worker 28 | 29 | [Worker to Worker communication](/common-language-guide/rpc) 30 | 31 | ### Set up the worker's filesystem 32 | 33 | [Worker filesystem](/common-language-guide/worker-filesystem) 34 | 35 | ### Share WIT packages between components 36 | 37 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 38 | 39 | ### Use LLMs 40 | 41 | [LLMs](/common-language-guide/llm) 42 | 43 | ### Use fork to achieve parallelism 44 | 45 | [Forking Workers](/common-language-guide/forking) 46 | 47 | 48 | -------------------------------------------------------------------------------- /src/pages/ccpp-language-guide/retries.mdx: -------------------------------------------------------------------------------- 1 | # Control the retry policy from C/C++ 2 | 3 | ### Using Golem's retry mechanism 4 | 5 | Golem applies a retry mechanism to all workers. In case of a failure, Golem will automatically recover the worker to the point before the failure and retry the operation. An exponential backoff and an upper limit on the number of retries are applied. 6 | 7 | If the maximum number of retries is reached, the worker will be marked as failed and no further invocations will be possible on it. 8 | 9 | This mechanism is automatic and applied to all kind of failures. To rely on it, just let the C code fail (for example by calling `abort()`). 10 | 11 | ### Customizing the retry policy 12 | 13 | The retry policy which controls the maximum number of retries and the exponential backoff is a global configuration of the Golem servers, but it can be customized for each worker. 14 | 15 | Once the `golem:api/host@1.1.0` interface is imported in the WIT file (see the [previous page for more information](/ccpp-language-guide/durability)), the retry policy can be controlled with the `golem_api_host_get_retry_policy` and `golem_api_host_set_retry_policy` functions. 16 | 17 | ```c 18 | golem_api_host_retry_policy_t previous; 19 | golem_api_host_get_retry_policy(&previous); 20 | 21 | golem_api_host_retry_policy_t current; 22 | current.max_attempts = 10; 23 | current.min_delay = 1000000000; // 1s 24 | current.max_delay = 1000000000; // 1s 25 | current.multiplier = 1; 26 | current.max_jitter_factor.is_some = false; 27 | golem_api_host_get_retry_policy(¤t); 28 | 29 | // ... 30 | 31 | golem_api_host_get_retry_policy(&previous); 32 | ``` 33 | 34 | The `golem_api_host_retry_policy_t` type itself is originated from Golem's WIT definition in the following way: 35 | 36 | ```wit 37 | /// Configures how the executor retries failures 38 | record retry-policy { 39 | /// The maximum number of retries before the worker becomes permanently failed 40 | max-attempts: u32, 41 | /// The minimum delay between retries (applied to the first retry) 42 | min-delay: duration, 43 | /// The maximum delay between retries 44 | max-delay: duration, 45 | /// Multiplier applied to the delay on each retry to implement exponential backoff 46 | multiplier: f64, 47 | /// The maximum amount of jitter to add to the delay 48 | max-jitter-factor: option 49 | } 50 | ``` 51 | -------------------------------------------------------------------------------- /src/pages/ccpp-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Setup development environment for C/C++ 5 | 6 | To write **Golem components** in C or C++, a couple of common WebAssembly tools need to be installed, as well as the latest version of the **WASM SDK**. 7 | 8 | ## Install WebAssembly tooling 9 | 10 | You will need both `wasm-tools` and `wit-bindgen` to work on C/C++ WebAssembly projects. 11 | Consult the [dedicated page](/installing-webassembly-tooling) for instructions on how to install them. 12 | 13 | ## Install WASI SDK 25.0 14 | 15 | Download and extract [WASI SDK 25.0](https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-25) somewhere. In the examples we assume that the `WASI_SDK_PATH` environment variable is set up pointing to the extracted SDK. 16 | 17 | The SDK contains a version of `Clang` that can compile to WebAssembly modules, which can be converted into Golem components using the `wit-bindgen` and `wasm-tools` command line tools. 18 | -------------------------------------------------------------------------------- /src/pages/ccpp-language-guide/updating.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Updating workers to newer versions of C/C++ components 5 | 6 | As described in the general [Workers](/concepts/workers) page, each worker runs on a specific version of the component it is based on, but it is possible to **update** a worker to a different version of the same component. 7 | 8 | ## Automatic update 9 | 10 | The **automatic update** mode has no C/C++-specific details and works as it is described in the general [Workers](/concepts/workers) page. 11 | 12 | ## Manual snapshot-based update 13 | 14 | Sometimes the change between two component versions is so large that the only solution to migrate worker's state to a new version is to manually implement this state transfer. 15 | 16 | This is done by implementing a `save-snapshot` function in the old component and a `load-snapshot` function in the new component. The snapshot is an array of bytes and it is the responsibility of the user to ensure that the snapshot is compatible between the two versions. 17 | 18 | These functions are defined in the `golem:api` WIT package and must be explicitly exported from the component's `world`. 19 | 20 | ### Implementing the save snapshot function 21 | 22 | The `save-snapshot` function must be explicitly exported from the component's `world` in it's `WIT` file: 23 | 24 | ```wit 25 | package golem:demo; 26 | 27 | interface api { 28 | // ... 29 | } 30 | 31 | world update-test-v3 { 32 | export golem:api/save-snapshot@1.1.0; 33 | 34 | export api; 35 | } 36 | ``` 37 | 38 | This requires manually adding all the WIT dependencies Golem provides to the component's `wit/deps` subdirectory, and importing some of them in the `Cargo.toml` file. 39 | 40 | 41 | ### Step 1: copy all the WIT dependencies 42 | 43 | First copy the whole contents of https://github.com/golemcloud/golem-wit/tree/main/wit/deps to the component's `wit/deps` directory. 44 | 45 | 46 | The `golem new` examples for C automatically create the `wit/deps` directory for you, except 47 | the `c-actor-minimal` one. 48 | 49 | 50 | ### Step 2: export the `save-snapshot` function 51 | 52 | Add the following line to the component's world in its main `WIT` file: 53 | 54 | ```wit 55 | export golem:api/save-snapshot@1.1.0; 56 | ``` 57 | 58 | ### Step 4: implement the `save-snapshot` function in C 59 | 60 | An example implementation that just writes out an empty array of bytes: 61 | 62 | ```c 63 | void exports_golem_api_save_snapshot_save(example_list_u8_t *ret) { 64 | ret->len = 0; 65 | ret->ptr = (uint8_t*)malloc(0); 66 | } 67 | ``` 68 | 69 | 70 | 71 | ### Implementing the load snapshot function 72 | 73 | Implementing the `load-snapshot` function in the new component requires the same prerequisites as the `save-snapshot` function. 74 | 75 | Once the WIT dependencies are set up, export the `load-snapshot` function in the following way: 76 | 77 | ```wit 78 | export golem:api/load-snapshot@1.1.0; 79 | ``` 80 | 81 | and then implement it in C: 82 | 83 | ```rust 84 | bool exports_golem_api_load_snapshot_load(example_list_u8_t *bytes, example_string_t *err) { 85 | example_string_set(err, "Failed to load snapshot"); 86 | return false; 87 | } 88 | 89 | ``` 90 | 91 | Note that the `load-snapshot` function can fail, indicating that it cannot load a previously saved snapshot. When the upgrade logic detects this, it reverts the worker to the previous version. 92 | 93 | If the snapshot can be loaded, the `load-snapshot` function must set up the worker's global state based on `bytes`, and return with `true`. 94 | -------------------------------------------------------------------------------- /src/pages/cli.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Card, Cards } from "nextra/components" 3 | 4 | # Golem CLI Introduction 5 | 6 | Golem CLI is a command-line interface for interacting with Golem. Golem CLI allows users to upload their components, launch new workers based on these components and call functions on running workers. 7 | 8 | ## Golem CLI versions 9 | There are precompiled binaries of two variants of the CLI here: 10 | 11 | - `golem` is the full version of the command line interface, including a locally runnable version of Golem itself. 12 | - `golem-cli` is a lightweight version of the command line interface, requiring a running Golem cluster 13 | 14 | In this documentation we will use the `golem` command in the snippets. 15 | 16 | ## Installation 17 | 18 | There are two ways to install any of the above described versions of Golem CLI: 19 | 20 | - Downloading a precompiled platform-specific binary 21 | - Installing from source using Rust tooling 22 | 23 | ### Downloading precompiled binaries 24 | 25 | You can download the precompiled version of `golem` (and `golem-cli`) from the following pages: 26 | 27 | 28 | 32 | 33 | 34 | We provide precompiled binaries for the following platforms: 35 | 36 | - Mac arm64 37 | - Mac x86_6 38 | - Linux arm64 39 | - Linux x86_64 40 | - Windows x86_64 41 | 42 | 43 | Some platforms may protect by default from running these downloaded binaries. You may need to 44 | allow running them in your system settings. 45 | 46 | 47 | ### Installing from source 48 | 49 | It is also possible to build it from source for yourself using Rust tooling. Refer to [the page about building Golem CLI for yourself](/cli/install-from-source) for more information. 50 | 51 | ## Profiles 52 | 53 | The Golem CLI can have multiple profiles configured, each selecting a specific Golem cluster to connect to, as well as some settings like the default output format. 54 | 55 | See the [Golem CLI profiles page](cli/profiles) for more information. 56 | 57 | ## Working with components 58 | 59 | Golem CLI can manage [Golem Components](concepts/components). See the [Golem CLI components page](cli/components) for details. 60 | 61 | ## Interacting with workers 62 | 63 | Golem CLI allows creating, invoking and observing [Golem Workers](concepts/workers). See the [Golem CLI workers page](cli/workers) for more information. 64 | -------------------------------------------------------------------------------- /src/pages/cli/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "app-manifest": "Application Manifest", 3 | "components": "Components", 4 | "workers": "Workers", 5 | "profiles": "Profiles", 6 | "permissions": "Permissions", 7 | "plugins": "Plugins", 8 | "shell-completion": "Shell Completion", 9 | "install-from-source": "Install from Source" 10 | } 11 | -------------------------------------------------------------------------------- /src/pages/cli/install-from-source.mdx: -------------------------------------------------------------------------------- 1 | import { Callout, Tabs } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Golem CLI installation from source 5 | 6 | If the precompiled binaries are not available for your platform, or prefer to install from source, you can build it with the Rust toolchain, 7 | 8 | ## Prerequisites 9 | To build `golem-cli` you need to use `cargo`, Rust's build tool, and the build will require `protoc`, the [protobuf](https://github.com/protocolbuffers/protobuf) compiler. 10 | 11 | To get `cargo` on your system, we recommend using [rustup](https://rustup.rs/): 12 | 13 | ```bash filename="Terminal" copy 14 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 15 | rustup install stable 16 | rustup default stable 17 | ``` 18 | 19 | To install `protoc` see [https://grpc.io/docs/protoc-installation/](https://grpc.io/docs/protoc-installation/). 20 | Make sure to install version **3.15 or higher**. 21 | 22 | ## Installing `golem-cli` 23 | 24 | The `golem-cli` command is the more lightweight version of Golem's command line interface, that allows you to interact with a running Golem cluster but it does not have a built-in local version of Golem itself. 25 | 26 | To install `golem-cli` from source, use `cargo install`: 27 | 28 | ```bash copy 29 | cargo install golem-cli --locked 30 | ``` 31 | 32 | This will create a binary file named `golem-cli` in the `~/.cargo/bin` directory. 33 | 34 | ## Installing `golem` 35 | 36 | The `golem` binary is the full version of Golem's command line interface, containing everything `golem-cli` has and also has a built-in local version of Golem itself. 37 | 38 | The `golem` package is not published to [crates.io](https://crates.io/) so in order to install it from source, follow the steps below. 39 | 40 | 41 | ### Clone the repository 42 | Clone the [GitHub repository](https://github.com/golemcloud/golem-cli): 43 | 44 | ```bash copy 45 | git clone https://github.com/golemcloud/golem-cli.git 46 | ``` 47 | ### Install cargo-make 48 | Install cargo-make using `cargo install`: 49 | 50 | ```bash copy 51 | cargo install cargo-make --locked 52 | ``` 53 | 54 | ### Build the project 55 | Build the project using `cargo make`: 56 | 57 | ```bash copy 58 | cargo make build 59 | ``` 60 | 61 | -------------------------------------------------------------------------------- /src/pages/cli/shell-completion.mdx: -------------------------------------------------------------------------------- 1 | import { Callout, Tabs } from "nextra/components" 2 | 3 | # Golem CLI Shell completion 4 | 5 | The `golem completion` command can be used to generate shell completions for many popular shells: 6 | 7 | 8 | 9 | ```shell copy 10 | golem completion --generate bash 11 | ``` 12 | 13 | 14 | ```shell copy 15 | golem completion --generate elvish 16 | ``` 17 | 18 | 19 | ```shell copy 20 | golem completion --generate fish 21 | ``` 22 | 23 | 24 | ```shell copy 25 | golem completion --generate powershell 26 | ``` 27 | 28 | 29 | ```shell copy 30 | golem completion --generate zsh 31 | ``` 32 | 33 | 34 | 35 | The above command will generate and print the shell completion script to the standard output, redirect the output into a file to save the script. Consult your shell documentation about where to place it. 36 | 37 | 38 | After every golem update, it is advised to also regenerate the shell completion to always 39 | include all the latest commands and flags. 40 | 41 | -------------------------------------------------------------------------------- /src/pages/common-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "shared-wit-packages": "Shared WIT Packages", 3 | "rpc": "Worker to Worker Communication", 4 | "wasi-http": "WASI HTTP Incoming Handler", 5 | "worker-filesystem": "Worker Filesytem", 6 | "llm": "Using LLMs", 7 | "rdbms": "Using Relational Databases", 8 | "forking": "Forking Workers" 9 | } 10 | -------------------------------------------------------------------------------- /src/pages/common-language-guide/forking.mdx: -------------------------------------------------------------------------------- 1 | import { Tabs } from "nextra/components" 2 | 3 | # Forking Workers 4 | 5 | ## Explanation 6 | 7 | Golem workers are single threaded. To achieve parallel execution, it is possible to spawn _child workers_ and communicate with them using RPC, as described on the [Worker to Worker communication page](/common-language-guide/rpc). 8 | 9 | A simpler way is to use the **fork API**. The fork API consists of a single host function, defined as the following: 10 | 11 | ```wit 12 | /// Indicates which worker the code is running on after `fork` 13 | enum fork-result { 14 | /// The original worker that called `fork` 15 | original, 16 | /// The new worker 17 | forked 18 | } 19 | 20 | /// Forks the current worker at the current execution point. The new worker gets the `new-name` worker name, 21 | /// and this worker continues running as well. The return value is going to be different in this worker and 22 | /// the forked worker. 23 | fork: func(new-name: string) -> fork-result; 24 | ``` 25 | 26 | When called, a new _worker_ is created using the given name, with exactly the same state as the one that called the `fork` function. The execution continues in both the original and the new workers, with a different `fork-result` result value in each. 27 | 28 | ## Usage 29 | 30 | Using this `fork` function from a component that was created from Golem's built-in templates is straightforward because access to the Golem specific host functions is already set up. 31 | 32 | The following code snippet demonstrates calling `fork` and continuing on two different parallel branches based on its result value: 33 | 34 | 35 | 36 | ```rust 37 | use golem_rust::{fork, ForkResult}; 38 | 39 | match fork("new-worker") { 40 | ForkResult::Original => { 41 | // ... 42 | } 43 | ForkResult::Forked => { 44 | // ... 45 | } 46 | } 47 | ``` 48 | 49 | 50 | ```typescript 51 | import { fork, type ForkResult } from "@golemcloud/golem-ts" 52 | 53 | switch (fork("new-name")) { 54 | case "original": { 55 | // ... 56 | break; 57 | } 58 | case "forked": { 59 | // ... 60 | break; 61 | } 62 | } 63 | ``` 64 | 65 | 66 | ```go 67 | switch golemhost.Fork("new-name") { 68 | case host.ForkResultOriginal: 69 | { 70 | // ... 71 | } 72 | case host.ForkResultForked: 73 | { 74 | // ... 75 | } 76 | } 77 | ``` 78 | 79 | 80 | ```python 81 | from my_component.imports import host 82 | 83 | if host.fork("new-name") == host.ForkResult.ORIGINAL: 84 | # ... 85 | pass 86 | else: 87 | # ... 88 | pass 89 | ``` 90 | 91 | 92 | ```c 93 | // TODO: Code example is not available yet 94 | ``` 95 | 96 | 97 | ```javascript 98 | // TODO: Code example is not available yet 99 | ``` 100 | 101 | 102 | ```zig 103 | // TODO: Code example is not available yet 104 | ``` 105 | 106 | 107 | ```moonbit 108 | // TODO: Code example is not available yet 109 | ``` 110 | 111 | 112 | ```scala.js 113 | // TODO: Code example is not available yet 114 | ``` 115 | 116 | 117 | -------------------------------------------------------------------------------- /src/pages/common-language-guide/shared-wit-packages.mdx: -------------------------------------------------------------------------------- 1 | import { Steps, Tabs } from "nextra/components" 2 | 3 | # Shared WIT packages 4 | 5 | When having multiple components in an application, we often want to share some of the WIT types between them. The application template used by `golem app new` contains a predefined way to add these shared packages. 6 | 7 | 8 | ### Create a new package 9 | 10 | The application's root directory has a `wit` directory, initially only containing an empty `common.wit` file. This file is just there to satisfy the requirements of some build tools, such as `wit-bindgen`. It should not be modified. 11 | 12 | Instead, create a new package in a subdirectory of `wit/deps`, for example `wit/deps/shared/shared.wit`. Each subdirectory of `wit/deps` must contain one particular package, but these packages can consist of multiple WIT files. 13 | 14 | For example the `shared.wit` file can define an interface with a few data types: 15 | 16 | ```wit 17 | package myapp:shared; 18 | 19 | interface types { 20 | type name = string; 21 | record user { 22 | id: u64; 23 | name: name; 24 | } 25 | } 26 | ``` 27 | 28 | ### Importing the shared package 29 | To import this shared package into one or more of the component's WIT files, just add an `import` statement to the component's _world_ like in the following example: 30 | 31 | ```wit 32 | package myapp:component1; 33 | 34 | // ... 35 | 36 | world component1 { 37 | import myapp:shared/types; 38 | 39 | // ... 40 | } 41 | ``` 42 | 43 | and use the `use` statement to import members of the shared interface into another one: 44 | 45 | ```wit 46 | interface api { 47 | use myapp:shared/types.{name, user}; 48 | 49 | // ... 50 | } 51 | ``` 52 | 53 | There is no other steps required - `golem app build` will automatically find the shared package and wire everything together as expected. 54 | 55 | ### Sharing code between components depending on shared WIT packages 56 | The application templates contain predefined "shared" libraries for most supported languages which can be used to shared code between components. 57 | 58 | These are located in the `common-*` directories, where `*` is the language. For example, the `common-rust` directory contains additional Rust crate that can be added as dependencies to the component implementations. 59 | 60 | When using **shared WIT packages** like above, it makes sense to write **shared code** depending on the bindings generated from these shared WIT packages. For example, there could be a JSON codec implemented for the above defined `user` record type which we want to use in multiple components. 61 | 62 | Doing so requires setting up a custom _binding generation_ step, which depends on the language being used: 63 | 64 | 65 | 66 | First add the `wit-bindgen` crate as a dependency to your shared crate under the `common-rust` directory: 67 | 68 | ```toml 69 | [dependencies] 70 | wit-bindgen = "0.37.0" 71 | ``` 72 | 73 | Then use the binding generator macro pointing to the **shared WIT package**, for example: 74 | 75 | ```rust 76 | use wit_bindgen::generate; 77 | 78 | generate!({ 79 | path: "../../wit", 80 | inline: r#" 81 | package common:inline; 82 | 83 | world common { 84 | import myapp:shared/types; 85 | } 86 | "#, 87 | // additional_derives: [serde::Deserialize, serde::Serialize], 88 | generate_all, 89 | generate_unused_types: true 90 | }); 91 | 92 | use crate::myapp::shared::types::*; 93 | ``` 94 | 95 | 96 | 97 | -------------------------------------------------------------------------------- /src/pages/concepts.mdx: -------------------------------------------------------------------------------- 1 | import { Cards, Card } from "nextra/components" 2 | 3 | # Concepts 4 | 5 | This section is a collection of Golem's primary **concepts**. 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /src/pages/concepts/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "reliability": "Reliability", 3 | "components": "Components", 4 | "workers": "Workers", 5 | "invocations": "Invocations", 6 | "worker-gateway": "Worker Gateway", 7 | "worker-to-worker-communication": "Worker to Worker Communication", 8 | "api-definitions": "API Definitions", 9 | "plugins": "Plugins" 10 | } 11 | -------------------------------------------------------------------------------- /src/pages/concepts/api-definitions.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Card, Cards } from "nextra/components" 3 | 4 | # Introduction 5 | 6 | Golem is a durable computing platform that makes it simple to build and deploy 7 | highly reliable distributed systems. 8 | 9 | As a serverless platform, Golem allows you to deploy components of your 10 | application, without having to write servers or implement protocols like HTTP, 11 | gRPC, or GraphQL. 12 | 13 | Without having to write any additional code, Golem provides you with the ability 14 | to trigger the creation of workers from your components based on HTTP API calls. 15 | 16 | Although useful for building tooling or quick prototypes, the generic APIs that 17 | Golem gives you to create and interact with your workers are usually not the 18 | polished, engineered APIs that you want to expose to other organizations, 19 | developers of mobile or web applications, or other backend teams. 20 | 21 | To allow you to stand up a custom API for your components, Golem supports a 22 | feature called _API Definitions_. API definitions give you the flexibility of 23 | having a precisely engineered API, but without any of the typical boilerplate. 24 | 25 | This page contains a high-level introduction to API definitions, with links to 26 | technical reference material. 27 | 28 | # API Definitions 29 | 30 | In Golem, an API Definition is similar to an OpenAPI specification for an API. 31 | Like OpenAPI specifications, API Definitions contain the following elements: 32 | 33 | - **Version**. The version defines the version of the API. 34 | - **Status**. The status defines whether the API is a draft, or whether it is 35 | published. Currently, published APIs may not be modified. 36 | - **Routes**. The routes are a list of individual HTTP endpoints. 37 | 38 | In an API definition, the routes define not just the structure of the overall 39 | HTTP, but also how invocation of these APIs triggers the creation and activation 40 | of workers. 41 | 42 | The next section introduces routes in more detail. 43 | 44 | ## Routes 45 | 46 | The elements of a route are as follows: 47 | 48 | - **Path**. The path of the route, such as `/users/{user-id}`. Paths may 49 | contain variables, which may be accessed inside the route binding. 50 | - **Method**. The method of the route, such as GET, PUT, POST, or DELETE. 51 | - **Binding**. The binding defines what worker will be created and invoked 52 | when the endpoint itself is invoked. 53 | 54 | In the following section, you will learn more about the binding. 55 | 56 | ### Bindings 57 | 58 | Bindings are the glue that connects your endpoint to an actual worker. 59 | Examples of what binding can do include invoking a worker, retrieving files from the worker filesystem and 60 | forwarding http requests to the wasi:http/proxy world. 61 | 62 | There are many different binding types that address various usecases, learn more about them [here](/http-api-definitions/api-definition-bindings). 63 | 64 | # Management 65 | 66 | There are a variety of ways to create and manage API Definition: 67 | 68 | - **Golem CLI**. The command-line interface lets you manage API definition. 69 | - **REST API**. The Golem REST API lets you manage API definition 70 | 71 | Both the CLI and REST API let you import an existing OpenAPI definition, with 72 | a custom per-endpoint extension that contains the binding. 73 | 74 | See more examples of implementing custom APIs [here](/invoke/making-custom-apis). 75 | -------------------------------------------------------------------------------- /src/pages/concepts/worker-gateway.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Card, Cards } from "nextra/components" 3 | 4 | # Introduction 5 | 6 | Golem is a durable computing platform that makes it simple to build and deploy 7 | highly reliable distributed systems. 8 | 9 | Golem is highly scalable, and partitions [workers](workers) across 10 | many worker executor nodes, which are each in charge of running a different 11 | subset of workers. 12 | 13 | Although partitioning workers across many nodes provides the benefit of 14 | horizontal scalability, it makes it more difficult to know which node is 15 | executing a particular worker. 16 | 17 | Even if you know which node is executing a worker, it would not be convenient to 18 | interact with the node directly, because it could fail, and you would have to 19 | implement logic that detects failure and waits until the worker is recovered on 20 | a new node before retrying the invocation. 21 | 22 | Moreover, the native protocol for [invoking](invocations) workers 23 | is low-level and inflexible, and most developers will not want to expose the 24 | invocation API to the outside world or to front-end applications. 25 | 26 | In order to address these issues, Golem has a _Worker Gateway_ service, which is 27 | effectively stateless and scaled independently of worker executor nodes. 28 | 29 | The primary functions of the _Worker Gateway_ are as follows: 30 | 31 | 1. Identify the node that is responsible for executing the worker being invoked, 32 | and route the invocation request to the node. 33 | 2. Transparently handle executor node failures by detecting failure, awaiting 34 | recovery, and retrying the invocation. 35 | 3. Support the execution of custom APIs, which satisfy arbitrary business and 36 | technical requirements. 37 | 38 | To learn more about how the Worker Gateway supports custom APIs, you can read 39 | the high-level [introduction to _API Definitions_](api-definitions), 40 | which links to further references. 41 | -------------------------------------------------------------------------------- /src/pages/concepts/worker-to-worker-communication.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Card, Cards } from "nextra/components" 3 | 4 | # Introduction 5 | 6 | Golem is a durable computing platform that makes it simple to build and deploy 7 | highly reliable distributed systems. 8 | 9 | The WASM component model eliminates the need for microservice architectures, 10 | since components written in different languages can interact with each other 11 | in-process (through component composition), without having to go through 12 | remote protocols like HTTP, gRPC, or JSON RPC. 13 | 14 | Despite this, however, there are times when remote procedure calls (RPC) are 15 | useful or necessary when developing applications on Golem: 16 | 17 | 1. You want to parallelize computation that cannot be done on a single worker, 18 | either due to lack of memory or lack of compute. 19 | 2. You want to partition state that is too large to store in a single worker; 20 | or, perhaps, you want to partition state that can fit in a single worker, but 21 | cannot be read and written fast enough due to contention. 22 | 23 | Both of these are examples require the development of a distributed system, 24 | where some combination of state and computation is distributed to improve 25 | performance, reduce latency, or improve scalability. 26 | 27 | To build a system that distributes state or compute, it is necessary to 28 | coordinate work, which requires RPC of some kind. 29 | 30 | Recognizing the critical nature of internal communication for many distributed 31 | systems, Golem provides a feature called _worker-to-worker communication_. This 32 | feature allows you to simply, and in a type-safe way, communicate between 33 | workers, with strong guarantees, such as reliable, exactly-once invocation 34 | semantics. 35 | 36 | # Technical details 37 | 38 | For worker-to-worker communication, Golem generates a type-safe client interface for each remotely callable component. These client interfaces are matching the component's interface, but packaged into a _resource_ that can be only constructed by giving enough information to know which _worker_ to communicate with. 39 | 40 | In case of _durable components_, this can be either a worker name (using the known name of the component) or a custom worker ID for special use cases. For _ephemeral components_, there is no need to specify a worker name, as each call will spawn a new ephemeral worker. 41 | 42 | Caller components are importing this generated client interface, so they no longer only use the host interfaces provided by Golem but also this dynamically created one. 43 | 44 | There are two ways to resolve this extra import: 45 | 46 | - Using the `wasm-rpc` binding type in the [application manifest](/app-manifest). In this case the import will be dynamically linked in the Golem server whenever a worker of the caller component is created. This is the recommended way as it has no additional build-time dependencies. 47 | - Using the `static-wasm-rpc` binding type in the [application manifest](/app-manifest). In this case the build tool (`golem app build`) will generate a Rust implementation of the client interface, compile it to WASM and *compose* it with the caller component's WASM module. This is useful for studying how the client implementation works, but as it requires the Rust toolchain to be installed, it is not recommended in general. 48 | 49 | # Learn More 50 | 51 | - [Worker to Worker Communication](/common-language-guide/rpc) 52 | - [The WASM-RPC host interface](/wasm-rpc) 53 | -------------------------------------------------------------------------------- /src/pages/debug.mdx: -------------------------------------------------------------------------------- 1 | # Debug workers 2 | 3 | There are many scenarios where looking into a worker's state can be useful. It is possible that a worker ran into a **failed state**, for example. Although transient errors are automatically retried, it is possible that a worker gets permantently failed due to a programming error. It is also possible that the worker is running, but not behaving as expected. 4 | 5 | There are several tools available in Golem to help in these situations. 6 | 7 | ### Querying the worker state 8 | 9 | By querying the worker state you can get some basic information about whether the worker is running, is suspended or failed, how many pending invocations it has, and what was the error message if it failed. 10 | 11 | To query the worker state using the `golem` command line tool, you can use the following command: 12 | 13 | ```shell copy 14 | golem worker get 15 | ``` 16 | 17 | ### Getting the worker's logs 18 | 19 | A worker can log messages in various ways: 20 | 21 | - Writing to the standard output (stdout) 22 | - Writing to the standard error (stderr) 23 | - Using the `log` function provided by WASI logging interface 24 | 25 | All of these log sources are preserved and can be examined in live by **connecting** to the worker: 26 | 27 | ```shell copy 28 | golem worker connect 29 | ``` 30 | 31 | There are also parameters for *invocation* that capture logs of the worker while an invocation is running. For more information see the [CLI worker reference](/cli/workers). 32 | 33 | ### Getting a worker's oplog 34 | 35 | The oplog of a worker is a journal of all the operations and events happened during the worker's lifetime. It is possible to retrieve a worker's oplog, as well as to filter it with search expressions. 36 | 37 | To get the whole oplog of a worker, you can use the following command: 38 | 39 | ```shell copy 40 | golem worker oplog 41 | ``` 42 | 43 | See the [CLI worker reference](/cli/workers) for more information about how to search the oplog. One debugging scenario can be to look for all oplog entries belonging to a given **idempotency key** that was provided with an invocation that did not behave as expected. Another can be looking for occurrences of external HTTP requests or log entries. 44 | 45 | ### Applying changes to a worker 46 | 47 | If the available information is not enough, it often helps to add more log lines to the worker. Recompiling the worker, updating the component and then updating the faulty worker will always succeed, if the only change was adding or removing log lines. 48 | 49 | ### Reverting changes to a worker 50 | 51 | The final tool available is **reverting** the worker. This can be done in two different ways: 52 | 53 | 1. **Undoing a given number of invocations**. In this case we specify a number (N), and the last N invocations will be treated as if they never happened. The worker's state will be restored to the point before these last N invocations. 54 | 2. **Reverting to a specific oplog index**. A more advanced use case is to revert the worker to a specific point in the oplog. This can be used to force rerunning some side effects such as external HTTP requests or database operations. 55 | 56 | To revert a worker using the `golem` command line interface, you can use the following command: 57 | 58 | ```shell copy 59 | golem worker revert --number-of-invocations 3 60 | ``` 61 | 62 | or 63 | 64 | ```shell copy 65 | golem worker revert --last-oplog-index 12345 66 | ``` 67 | -------------------------------------------------------------------------------- /src/pages/deploy/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "docker": "Docker", 3 | "kubernetes": "Kubernetes", 4 | "golem-cloud": "Golem Cloud" 5 | } 6 | -------------------------------------------------------------------------------- /src/pages/deploy/docker.mdx: -------------------------------------------------------------------------------- 1 | # Deploy using Docker 2 | 3 | To get started we recommend using the Docker Compose file from the [Golem Docker examples](https://github.com/golemcloud/golem/tree/main/docker-examples). You will need to have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your system. 4 | 5 | Once you have Docker Compose installed, you can make use of docker-compose file in Golem repository to spin up Golem. 6 | 7 | ```bash filename="Terminal" copy 8 | # Download an example docker-compose file along with .env file that has a few common configurations 9 | curl -O https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/published-postgres/compose.yaml -O https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/published-postgres/.env 10 | 11 | # Start Golem with backend storage as PostgreSQL and Redis 12 | docker compose -f compose.yaml up 13 | ``` 14 | 15 | You may need to modify it to suit your needs. 16 | 17 | ### Troubleshooting 18 | 19 | - If you are running into any port conflicts you can modify the [.env](https://github.com/golemcloud/golem/blob/main/docker-examples/.env) file that was downloaded as part of the above curl command. 20 | - It has come to our note that, in some cases, the docker compose result in the following error: 21 | 22 | ```bash 23 | error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ` 24 | ``` 25 | 26 | In this situation, the best possible solution is to rename `credsStore` to `credStore` in the `.docker/config.json` file. 27 | 28 | - If you still face issues, try the sqlite version of the docker-compose file: 29 | 30 | ```bash 31 | docker compose -f docker-compose-sqlite.yaml up 32 | ``` 33 | 34 | ### Accessing Golem APIs 35 | 36 | [Golem APIs](/rest-api/oss-rest-api) are exposed on port 9881 by default. Worker [API Gateway](/concepts/worker-gateway) endpoint is exposed under port 9006. 37 | -------------------------------------------------------------------------------- /src/pages/deploy/golem-cloud.mdx: -------------------------------------------------------------------------------- 1 | # Deploy to Golem Cloud 2 | 3 | Golem Cloud is hosted version of Golem. It is easiest and fastest way to run Golem [workers](/concepts/workers), 4 | in the cloud, at scale, without any infrastructure setup or maintenance required. 5 | 6 | Golem Cloud can be managed by: 7 | 8 | - [Web management console](https://console.golem.cloud/) 9 | - [golem-cloud-cli](/cli) 10 | - [REST API](/rest-api/cloud-rest-api) 11 | -------------------------------------------------------------------------------- /src/pages/deploy/kubernetes.mdx: -------------------------------------------------------------------------------- 1 | # Deploy to Kubernetes 2 | 3 | To get started we recommend using the [Golem Helm Chart](https://github.com/golemcloud/golem/blob/main/kube/golem-chart). 4 | You will need to have [Helm](https://helm.sh/docs/intro/quickstart/) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally 5 | and running [kubernetes](https://kubernetes.io/docs/concepts/overview/) cluster (for testing you can use [Docker Desktop](https://docs.docker.com/desktop/kubernetes/) or [minikube](https://minikube.sigs.k8s.io/docs/start)). 6 | 7 | For quick start we recommend to download content of [kube](https://github.com/golemcloud/golem/blob/main/kube/) directory from Golem [repository](https://github.com/golemcloud/golem/tree/main) and run `deploy.sh` script: 8 | 9 | ```bash copy 10 | ./deploy.sh -n golem 11 | ``` 12 | 13 | which will deploy Golem with Redis and PostgreSQL to kubernetes namespace `golem`. 14 | Kubernetes [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) are used to store Golem's data. 15 | [Nginx ingress controller](https://github.com/kubernetes/ingress-nginx) is used to expose [Golem APIs](/rest-api/oss-rest-api) (http with port 80). For testing, you may need to change [golem-cli](/cli) configuration to use proper host and port. 16 | Worker [API Gateway](/concepts/worker-gateway) endpoint is exposed under port 9006. 17 | 18 | For production is preferable to use separate PostgreSQL cluster, Redis cluster and reliable Shared File System or S3 for Blob storage. 19 | 20 | See Golem Helm Chart [values.yaml](https://github.com/golemcloud/golem/blob/main/kube/golem-chart/values.yaml) and [readme](https://github.com/golemcloud/golem/blob/main/kube/README.md) for more details. 21 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "zig-language-guide": "Zig", 3 | "scalajs-language-guide": "Scala.js", 4 | "moonbit-language-guide": "MoonBit" 5 | } 6 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/moonbit-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps" 10 | } 11 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/moonbit-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in MoonBit 5 | 6 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 7 | 8 | ```shell copy 9 | golem app build 10 | ``` 11 | 12 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 13 | 14 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 15 | 16 | ```shell copy 17 | golem component add 18 | ``` 19 | 20 | ## Regenerating the stubs 21 | A custom command is provided to regenerate the stubs to be implemented: 22 | 23 | ```shell copy 24 | golem app regenerate-stubs 25 | ``` 26 | 27 | This command will **rewrite the stub code** in the source directory, removing any existing change into it! Make sure the previous code is copied elsewhere before running this command. It is not mandatory to ever run this command, but then when the exported WIT interface changes, the changes will have to be reflected manually in the source code. 28 | 29 | ## Under the hood 30 | Building Golem components written in MoonBit involves a few steps. 31 | 32 | 33 | ### Generating bindings 34 | The first step is to generate bindings using `wit-bindgen moonbit`. 35 | 36 | ### Building the component 37 | Building the component into core WASM module using `moon build --target wasm`. 38 | 39 | ### Embedding the WIT specification 40 | Before converting the resulting WASM module into a Golem component, the WIT specification is embedded in a custom section using `wasm-tools component embed`. 41 | 42 | ### Converting to a Golem component 43 | Finally the WASM module is converted into a component using `wasm-tools component new`. 44 | 45 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/moonbit-language-guide/defining-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Defining Golem Components in MoonBit 4 | 5 | ## Creating a project 6 | 7 | Golem's **command line interface** provides a set of predefined, Golem-specific **templates** to choose from as a starting point. 8 | 9 | To get started from scratch, first create a new application using the `MoonBit` template: 10 | 11 | ```shell copy 12 | golem app new my-app moonbit 13 | cd my-app 14 | ``` 15 | 16 | An application can consist of multiple components. Add a new component by choosing from one of the available templates. To see the list of available templates, run: 17 | 18 | ```shell copy 19 | golem component new 20 | ``` 21 | 22 | Then create a new component using the chosen template: 23 | 24 | ```shell copy 25 | golem component new moonbit my-component 26 | ``` 27 | 28 | ## Specification-first approach 29 | 30 | Golem and the MoonBit toolchain currently requires defining the component's interface using the **WebAssembly Interface Type (WIT)** format. See [the official documentation of this format](https://component-model.bytecodealliance.org/design/wit.html) for reference. 31 | 32 | Each new project generated with `golem` contains a `wit` directory with at least one `.wit` file defining a `world`. This world can contain **exports** (exported functions and interfaces) and these exports will be the compiled Golem component's public API. 33 | 34 | The first time a component is compiled (see the [Building Components page](/experimental-languages/moonbit-language-guide/building-components) for details), a couple of files get generated in the `ffi`, `gen`, `interface` and `world` directories. This module contains the MoonBit definitions of all the data types and interfaces defined in the `WIT` file(s). 35 | 36 | To **implement** the specification written in WIT, the MoonBit code must implement some of these generated exported functions defined in the generated files. 37 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/moonbit-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the MoonBit development environment](/experimental-languages/moonbit-language-guide/setup) and learning the basic steps [writing a Golem component](/experimental-languages/moonbit-language-guide/defining-components) and [building them](/experimental-languages/moonbit-language-guide/building-components), please consider learning about the following topics: 6 | 7 | Note that as MoonBit support is **experimental**, not all the features are documented yet. Please refer to one of the fully supported language guides (such as [Rust](/rust-language-guide/next-steps)) to learn more. 8 | 9 | 10 | ### Call other workers from a worker 11 | 12 | [Worker to Worker communication](/common-language-guide/rpc) 13 | 14 | ### Set up the worker's filesystem 15 | 16 | [Worker filesystem](/common-language-guide/worker-filesystem) 17 | 18 | ### Share WIT packages between components 19 | 20 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 21 | 22 | ### Use LLMs 23 | 24 | [LLMs](/common-language-guide/llm) 25 | 26 | ### Use fork to achieve parallelism 27 | 28 | [Forking Workers](/common-language-guide/forking) 29 | 30 | 31 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/moonbit-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Setup development environment for MoonBit 5 | 6 | To write **Golem components** in MoonBit, a couple of common WebAssembly tools need to be installed, as well as the latest MoonBit compiler. 7 | 8 | ## Install WebAssembly tooling 9 | 10 | First of all, to install `wasm-tools` via `cargo`, you need to install the latest stable version of Rust. The recommended way to do so is using [https://rustup.rs](https://rustup.rs/): 11 | 12 | 13 | 14 | ### Install Rust 15 | 16 | Install rustup 17 | 18 | ```bash copy 19 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 20 | ``` 21 | 22 | Install the latest stable version of Rust 23 | 24 | ```bash copy 25 | rustup install stable && rustup default stable 26 | ``` 27 | 28 | Add the WASI target 29 | 30 | ```bash copy 31 | rustup target add wasm32-wasip1 32 | ``` 33 | 34 | ### Install `wasm-tools` 35 | 36 | ```bash copy 37 | cargo install --force --locked wasm-tools@1.223.0 38 | ``` 39 | 40 | Confirm the installation: 41 | 42 | ```bash 43 | wasm-tools --version 44 | wasm-tools 1.223.0 45 | ``` 46 | 47 | ### Install `wit-bindgen` 48 | 49 | ```bash copy 50 | cargo install --force --locked wit-bindgen-cli@0.40.0 51 | ``` 52 | 53 | Confirm the installation: 54 | 55 | ```bash 56 | wit-bindgen --version 57 | wit-bindgen-cli 0.40.0 58 | ``` 59 | 60 | 61 | 62 | 63 | Golem requires a **specific version** of `wasm-tools`, and `wit-bindgen`. Please make sure the 64 | correct version is installed with the commands described above. 65 | 66 | 67 | ## Install MoonBit 68 | 69 | Install the latest MoonBit compiler using [the official instructions](https://www.moonbitlang.com/download/). The documentation and examples were created using MoonBit **0.1.20250310**. 70 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/scalajs-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps" 10 | } 11 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/scalajs-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in Scala.js 5 | 6 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 7 | 8 | ```shell copy 9 | golem app build 10 | ``` 11 | 12 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 13 | 14 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 15 | 16 | ```shell copy 17 | golem component add 18 | ``` 19 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/scalajs-language-guide/defining-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Defining Golem Components in Scala.js 4 | 5 | ## Creating a project 6 | 7 | Golem's **command line interface** provides a set of predefined, Golem-specific **templates** to choose from as a starting point. 8 | 9 | To get started from scratch, first create a new application using the `Scala.js` template: 10 | 11 | ```shell copy 12 | golem app new my-app scalajs 13 | cd my-app 14 | ``` 15 | 16 | An application can consist of multiple components. Add a new component by choosing from one of the available templates. To see the list of available templates, run: 17 | 18 | ```shell copy 19 | golem component new 20 | ``` 21 | 22 | Then create a new component using the chosen template: 23 | 24 | ```shell copy 25 | golem component new scalajs my-component 26 | ``` 27 | 28 | ## Specification-first approach 29 | 30 | Golem and the Scala.js toolchain currently requires defining the component's interface using the **WebAssembly Interface Type (WIT)** format. See [the official documentation of this format](https://component-model.bytecodealliance.org/design/wit.html) for reference. 31 | 32 | Each new project generated with `golem` contains a `wit` directory with at least one `.wit` file defining a `world`. This world can contain **exports** (exported functions and interfaces) and these exports will be the compiled Golem component's public API. 33 | 34 | When a component is compiled (see the [Building Components page](/experimental-languages/scalajs-language-guide/building-components) for details), a couple of scala packages get generated in the `target//src_managed` directory. These packages contains the Scala definitions of all the data types and interfaces defined in the `WIT` file(s). 35 | 36 | To **implement** the specification written in WIT, the Scala.js code must implement some of these generated exported traits with proper `@JSExport` annotations. 37 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/scalajs-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the Scala.js development environment](/experimental-languages/scalajs-language-guide/setup) and learning the basic steps [writing a Golem component](/experimental-languages/scalajs-language-guide/defining-components) and [building them](/experimental-languages/scalajs-language-guide/building-components), please consider learning about the following topics: 6 | 7 | Note that as Scala.js support is **experimental**, not all the features are documented yet. Please refer to one of the fully supported language guides (such as [Rust](/rust-language-guide/next-steps)) to learn more. 8 | 9 | 10 | ### Call other workers from a worker 11 | 12 | [Worker to Worker communication](/common-language-guide/rpc) 13 | 14 | ### Set up the worker's filesystem 15 | 16 | [Worker filesystem](/common-language-guide/worker-filesystem) 17 | 18 | ### Share WIT packages between components 19 | 20 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 21 | 22 | ### Use LLMs 23 | 24 | [LLMs](/common-language-guide/llm) 25 | 26 | ### Use fork to achieve parallelism 27 | 28 | [Forking Workers](/common-language-guide/forking) 29 | 30 | 31 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/scalajs-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Setup development environment for Scala.js 5 | 6 | To write **Golem components** in Scala.js, a special version of `wit-bindgen` needs to be installed, as well as the `sbt` build tool and Node.js and `npm`. 7 | 8 | ## Install WebAssembly tooling 9 | 10 | First of all, to install `wit-bindgen-scalajs` via `cargo`, you need to install the latest stable version of Rust. The recommended way to do so is using [https://rustup.rs](https://rustup.rs/): 11 | 12 | 13 | 14 | ### Install Rust 15 | 16 | Install rustup 17 | 18 | ```shell copy 19 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 20 | ``` 21 | 22 | Install the latest stable version of Rust 23 | 24 | ```shell copy 25 | rustup install stable && rustup default stable 26 | ``` 27 | 28 | Add the WASI target 29 | 30 | ```shell copy 31 | rustup target add wasm32-wasip1 32 | ``` 33 | 34 | ### Install `wit-bindgen-scalajs` 35 | 36 | ```shell copy 37 | cargo install --git https://github.com/vigoo/wit-bindgen-scalajs wit-bindgen-cli --locked 38 | ``` 39 | 40 | Confirm the installation: 41 | 42 | ```shell 43 | wit-bindgen-scalajs --version 44 | wit-bindgen-cli 0.37.0 (f30fdae38 2025-02-23) 45 | ``` 46 | 47 | 48 | 49 | 50 | Golem requires a **specific version** of `wasm-tools`, and `wit-bindgen`. Please make sure the 51 | correct version is installed with the commands described above. 52 | 53 | 54 | ## Install Node.js and npm 55 | 56 | Install **Node.js** and **npm** to your system by following the official [instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). 57 | 58 | ## Install sbt 59 | 60 | Follow the official [instructions](https://www.scala-sbt.org/download.html) to install sbt. 61 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/zig-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps" 10 | } 11 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/zig-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in Zig 5 | 6 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 7 | 8 | ```shell copy 9 | golem app build 10 | ``` 11 | 12 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 13 | 14 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 15 | 16 | ```shell copy 17 | golem component add 18 | ``` 19 | 20 | ## Under the hood 21 | Building Golem components written in Zig involves a few steps. 22 | 23 | If the project was created with `golem new`, it already has a `build.zig` file that incorporates all the necessary steps to build the component, so it is enough to run: 24 | 25 | ```shell 26 | $ zig build 27 | ``` 28 | 29 | In details, building the component requires the following steps: 30 | 31 | 32 | ### Generate the C bindings from the WIT files 33 | 34 | ```zig 35 | const bindgen = b.addSystemCommand(&.{ "wit-bindgen", "c", "--autodrop-borrows", "yes", "./wit", "--out-dir", "src/bindings" }); 36 | ``` 37 | 38 | ### Use the WASM32/WASI target 39 | 40 | ```zig 41 | const wasm = b.addExecutable(.{ .name = "main", .root_source_file = b.path("src/main.zig"), .target = b.resolveTargetQuery(.{ 42 | .cpu_arch = .wasm32, 43 | .os_tag = .wasi, 44 | }), .optimize = optimize }); 45 | ``` 46 | 47 | ### Include the generated C bindings 48 | 49 | ```zig 50 | const binding_root = "src/bindings"; 51 | var binding_root_dir = try std.fs.cwd().openDir(binding_root, .{ .iterate = true}); 52 | defer binding_root_dir.close(); 53 | var it = try binding_root_dir.walk(b.allocator); 54 | while (try it.next()) |entry| { 55 | switch (entry.kind) { 56 | .file => { 57 | const path = b.pathJoin(&.{ binding_root, entry.path }); 58 | if (std.mem.endsWith(u8, entry.basename, ".c")) { 59 | wasm.addCSourceFile(.{ .file = b.path(path), .flags = &.{} }); 60 | } else if (std.mem.endsWith(u8, entry.basename, ".o")) { 61 | wasm.addObjectFile(b.path(path)); 62 | } 63 | }, 64 | else => continue, 65 | } 66 | } 67 | 68 | wasm.addIncludePath(b.path(binding_root)); 69 | wasm.linkLibC(); 70 | 71 | wasm.step.dependOn(&bindgen.step); 72 | ``` 73 | 74 | ### Package it into a WASM component 75 | 76 | The resulting WASM file is a WebAssembly module, not a component. To be able to use it as a **Golem component**, use `wasm-tools` to package the module as a component: 77 | 78 | ```zig 79 | const adapter = b.option([]const u8, "adapter", "Path to the Golem Tier1 WASI adapter") orelse "adapters/tier1/wasi_snapshot_preview1.wasm"; 80 | const out = try std.fmt.allocPrint(b.allocator, "zig-out/bin/{s}", .{wasm.out_filename}); 81 | const component = b.addSystemCommand(&.{ "wasm-tools", "component", "new", out, "-o", "zig-out/bin/component.wasm", "--adapt", adapter }); 82 | component.step.dependOn(&wasm.step); 83 | 84 | b.installArtifact(wasm); 85 | b.getInstallStep().dependOn(&component.step); 86 | ``` 87 | 88 | 89 | Note that the `adapters/tier1/wasi_snapshot_preview1.wasm` file is placed in the project's directory when using `golem new` to create the new project. 90 | 91 | If needed, it can be manually downloaded from https://github.com/golemcloud/golem-wit/blob/main/adapters/tier1/wasi_snapshot_preview1.wasm 92 | 93 | 94 | 95 | 96 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/zig-language-guide/defining-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Defining Golem Components in Zig 4 | 5 | ## Creating a project 6 | 7 | Golem's **command line interface** provides a set of predefined, Golem-specific **templates** to choose from as a starting point. 8 | 9 | To get started from scratch, first create a new application using the `Zig` template: 10 | 11 | ```shell copy 12 | golem app new my-app zig 13 | cd my-app 14 | ``` 15 | 16 | An application can consist of multiple components. Add a new component by choosing from one of the available templates. To see the list of available templates, run: 17 | 18 | ```shell copy 19 | golem component new 20 | ``` 21 | 22 | Then create a new component using the chosen template: 23 | 24 | ```shell copy 25 | golem component new zig my-component 26 | ``` 27 | 28 | ## Specification-first approach 29 | 30 | Golem and the Zig (and C/C++) toolchain currently requires defining the component's interface using the **WebAssembly Interface Type (WIT)** format. See [the official documentation of this format](https://component-model.bytecodealliance.org/design/wit.html) for reference. 31 | 32 | Each new project generated with `golem` contains a `wit` directory with at least one `.wit` file defining a `world`. This world can contain **exports** (exported functions and interfaces) and these exports will be the compiled Golem component's public API. 33 | 34 | The first time a component is compiled (see the [Building Components page](/experimental-languages/zig-language-guide/building-components) for details), a couple of files (`example.c`, `example.h` and `example_component_type.o` if the component name was `example`) get generated in the `src/bindings` directory. This module contains the C definitions of all the data types and interfaces defined in the `WIT` file(s). 35 | 36 | To **implement** the specification written in WIT, the Zig code must implement some of these generated exported functions defined in the generated header file. 37 | 38 | As currently there is no Zig-specific binding generator, for more details, check the [C/C++ guide for defining components](/ccpp-language-guide/defining-components). 39 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/zig-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the Zig development environment](/experimental-languages/zig-language-guide/setup) and learning the basic steps [writing a Golem component](/experimental-languages/zig-language-guide/defining-components) and [building them](/experimental-languages/zig-language-guide/building-components), please consider learning about the following topics: 6 | 7 | Note that as there is no Zig-specific Golem SDK and binding generator, the lineked pages below refer to the C/C++ language guide. 8 | 9 | 10 | ### Making HTTP requests from a Golem component 11 | Learn how to [send HTTP requests from a Golem component written in C/C++](/ccpp-language-guide/http). 12 | 13 | ### Control durability guarantees 14 | 15 | Check how the Golem runtime API can [control various durability settings](/ccpp-language-guide/durability) of Golem. 16 | 17 | ### Automatic retries 18 | 19 | Learn about Golem's retry mechanism and [how it can be customized](/ccpp-language-guide/retries). 20 | 21 | ### Promises 22 | 23 | Create and use [promises](/ccpp-language-guide/promises) to await external events from within a running worker. 24 | 25 | ### Using WASI interfaces 26 | 27 | See what low-level [WASI interfaces](/ccpp-language-guide/wasi) are available and how they can be used from C/C++. 28 | 29 | ### Call other workers from a worker 30 | 31 | [Worker to Worker communication](/common-language-guide/rpc) 32 | 33 | ### Set up the worker's filesystem 34 | 35 | [Worker filesystem](/common-language-guide/worker-filesystem) 36 | 37 | ### Share WIT packages between components 38 | 39 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 40 | 41 | ### Use LLMs 42 | 43 | [LLMs](/common-language-guide/llm) 44 | 45 | ### Use fork to achieve parallelism 46 | 47 | [Forking Workers](/common-language-guide/forking) 48 | 49 | 50 | -------------------------------------------------------------------------------- /src/pages/experimental-languages/zig-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Setup development environment for Zig 5 | 6 | To write **Golem components** in Zig, a couple of common WebAssembly tools need to be installed, as well as the latest Zig compiler. 7 | 8 | ## Install WebAssembly tooling 9 | 10 | First of all, to install `wasm-tools` via `cargo`, you need to install the latest stable version of Rust. The recommended way to do so is using [https://rustup.rs](https://rustup.rs/): 11 | 12 | 13 | 14 | ### Install Rust 15 | 16 | Install rustup 17 | 18 | ```bash copy 19 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 20 | ``` 21 | 22 | Install the latest stable version of Rust 23 | 24 | ```bash copy 25 | rustup install stable && rustup default stable 26 | ``` 27 | 28 | Add the WASI target 29 | 30 | ```bash copy 31 | rustup target add wasm32-wasip1 32 | ``` 33 | 34 | ### Install `wasm-tools` 35 | 36 | ```bash copy 37 | cargo install --force --locked wasm-tools@1.223.0 38 | ``` 39 | 40 | Confirm the installation: 41 | 42 | ```bash 43 | wasm-tools --version 44 | wasm-tools 1.223.0 45 | ``` 46 | 47 | ### Install `wit-bindgen` 48 | 49 | ```bash copy 50 | cargo install --force --locked wit-bindgen-cli@0.37.0 51 | ``` 52 | 53 | Confirm the installation: 54 | 55 | ```bash 56 | wit-bindgen --version 57 | wit-bindgen-cli 0.37.0 58 | ``` 59 | 60 | 61 | 62 | 63 | Golem requires a **specific version** of `wasm-tools`, and `wit-bindgen`. Please make sure the 64 | correct version is installed with the commands described above. 65 | 66 | 67 | ## Install Zig 68 | 69 | Install the latest Zig compiler using [the official instructions](https://ziglang.org/learn/getting-started/#installing-zig). The documentation and examples were created using Zig **0.13**. 70 | -------------------------------------------------------------------------------- /src/pages/fundamentals.mdx: -------------------------------------------------------------------------------- 1 | # Fundamentals 2 | 3 | Golem is a serverless computing platform that helps you build and deploy reliable distributed systems with simple code. 4 | 5 | In this section, you will learn some key terms and architecture that will help you better understand Golem. 6 | 7 | ## Key Terms 8 | 9 | - **WASM**. [WebAssembly](https://webassembly.org/), or WASM, for short, is a specification for a portable and secure 10 | virtual machine. Software compiled to WASM can execute on any platform and architecture using a _WASM Runtime_. 11 | - **Components**. In WebAssembly, _components_ are the basic building block of applications, backends, and web services. 12 | Components requires certain capabilities from the host platform (like input/output), and expose a typed public API. 13 | - **Workers**. In Golem, workers are running instances created from components, with their own resources, such as RAM, 14 | file system, and environment variables. Workers are created from external events like requests or by other workers. 15 | - **Invocations**. In Golem, the fundamental unit of work is an invocation of a function that is part of a worker's 16 | typed public API. Functions may require typed parameters as input and may return typed values as output. 17 | - **High-Reliability**. Highly reliable systems must execute critical logic uninterrupted, even through faults, 18 | updates, and cloud flakiness. Golem provides transparent high-reliability, regardless of language or technology stack. 19 | - **WIT**. WIT is a standard of WASM, similar to Protobuf, which allows developers to export a typed public API from 20 | components. Through the Worker Gateway, Golem lets you build HTTP or gRPC APIs atop these typed public APIs. 21 | 22 | ## Golem Architecture 23 | 24 | Golem is architected as a series of independent and modular components, ranging from command-line tools to core systems 25 | responsible for deployment and execution. 26 | 27 | - **CLI**. _Golem CLI_ is a command-line interface to Golem, which has the ability to create and manage components 28 | and workers, perform invocations, and even connect to live workers for diagnostics and troubleshooting. 29 | - **Worker Gateway**. _Worker Gateway_ executes requests by delegating their processing to specific functions on 30 | specified workers. Worker Gateway can extract worker input from JSON, and produce JSON from worker output. 31 | - **Worker Executor**. _Worker Executor_ creates and executes the logic of many individual workers, potentially 32 | created from different components, exposing their public typed API via the Worker Gateway. 33 | - **Golem Services**. _Golem Services_ runs a variety of different HTTP endpoints that allow programmatic management 34 | of all the features of Golem. CLI and Console are both implemented atop Golem Services. 35 | - **Shard Manager**. _Shard Manager_ handles both supervision of individual executor nodes in the Golem cluster and the 36 | task of partitioning all workers across the available executor nodes in a Golem cluster. 37 | - **Golem Cloud**. _Golem Cloud_ is the fully managed version of Golem, suitable for companies looking for a true 38 | zero-ops approach to building highly-reliable distributed systems with simple code. 39 | - **Console**. _Console_ is a graphical user-interface designed to help manage accounts, components, and workers on 40 | Golem Cloud. It provides high-level ways of performing many of the same tasks that are supported by CLI. 41 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps", 10 | "-- golem-sdk": { 11 | "type": "separator", 12 | "title": "Golem SDK" 13 | }, 14 | "golem-go-sdk": "Setting up the Golem Go SDK", 15 | "http": "HTTP client", 16 | "durability": "Durability", 17 | "retries": "Retries", 18 | "transactions": "Transactions", 19 | "promises": "Promises", 20 | "worker-metadata": "Accessing worker metadata", 21 | "updating": "Updating Workers", 22 | "wasi": "WASI" 23 | } 24 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in Go 5 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 6 | 7 | ```shell copy 8 | golem app build 9 | ``` 10 | 11 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 12 | 13 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 14 | 15 | ```shell copy 16 | golem component add 17 | ``` 18 | 19 | ## Under the hood 20 | 21 | Building Golem components written in Go requires a series of steps. 22 | 23 | In details, building the component requires the following steps: 24 | 25 | 26 | ### Generate the Go bindings 27 | 28 | Use the `wit-bindgen-go` tool to generate the Go bindings from the WIT files: 29 | 30 | ```shell 31 | $ go get -tool go.bytecodealliance.org/cmd/wit-bindgen-go 32 | $ go tool wit-bindgen-go generate --out binding --world world-name ./wit 33 | ``` 34 | 35 | ### Compile the Go code 36 | 37 | Using the TinyGo compiler, compile the Go code into a WebAssembly module: 38 | 39 | ```shell 40 | $ tinygo build -target=wasip2 -wit-package ./wit -wit-world world-name -tags=purego -o go_example.wasm main.go 41 | ``` 42 | 43 | The resulting WASM file is a **component** ready to be uploaded to Golem. 44 | 45 | ### Reducing the component's size 46 | 47 | The generated component's size can be reduced by stripping some parts of it using the `wasm-tools strip` command: 48 | 49 | ```shell 50 | $ wasm-tools strip go_example.wasm -o go_example_stripped.wasm 51 | ``` 52 | 53 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/golem-go-sdk.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Setting up the Golem Go SDK 5 | 6 | 7 | If the project was created with `golem component new`, it already has the Golem Go SDK set up and most of these 8 | steps can be ignored. You may still need to customize your **imports** in the component's WIT. 9 | 10 | 11 | If setting up the [Golem Go SDK](https://github.com/golemcloud/golem-go) manually, the following steps are required: 12 | 13 | 14 | ### Add the Golem Go SDK as a dependency 15 | 16 | Add the following dependency to the project: 17 | 18 | ```shell 19 | $ go get github.com/golemcloud/golem-go 20 | ``` 21 | 22 | ### Add all the supported WIT files into the project 23 | 24 | The project's `wit/deps` directory must contain all the WIT files from the [golem-wit](https://github.com/golemcloud/golem-wit/tree/main/wit/deps) repository. 25 | 26 | ### Importing WITs into the component's world: 27 | 28 | If the project's WIT file was like this: 29 | 30 | ```wit 31 | package golem:demo; 32 | 33 | world go-example { 34 | export api; 35 | } 36 | ``` 37 | 38 | Modify it in the following way: 39 | 40 | ```wit 41 | package golem:demo; 42 | 43 | world go-example { 44 | import golem:api/host@1.1.6; 45 | import golem:rpc/types@0.2.0; 46 | 47 | import wasi:blobstore/blobstore; 48 | import wasi:blobstore/container; 49 | import wasi:cli/environment@0.2.0; 50 | import wasi:clocks/wall-clock@0.2.0; 51 | import wasi:clocks/monotonic-clock@0.2.0; 52 | import wasi:filesystem/preopens@0.2.0; 53 | import wasi:filesystem/types@0.2.0; 54 | import wasi:http/types@0.2.0; 55 | import wasi:http/outgoing-handler@0.2.0; 56 | import wasi:io/error@0.2.0; 57 | import wasi:io/poll@0.2.0; 58 | import wasi:io/streams@0.2.0; 59 | import wasi:keyvalue/eventual-batch@0.1.0; 60 | import wasi:keyvalue/eventual@0.1.0; 61 | import wasi:logging/logging; 62 | import wasi:random/random@0.2.0; 63 | import wasi:random/insecure@0.2.0; 64 | import wasi:random/insecure-seed@0.2.0; 65 | import wasi:sockets/ip-name-lookup@0.2.0; 66 | import wasi:sockets/instance-network@0.2.0; 67 | 68 | export api; 69 | } 70 | ``` 71 | 72 | 73 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/http.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # HTTP requests in Go 4 | 5 | 6 | Check the [page about setting up the Golem Go SDK](/go-language-guide/golem-go-sdk) to make sure the SDK is available in your component. 7 | 8 | 9 | Golem implements the [WASI HTTP](https://github.com/WebAssembly/wasi-http) interfaces so any library built on this specification can be used from Golem components to communicate with external services. 10 | 11 | By using the [Golem Go SDK](/go-language-guide/golem-go-sdk), Go's built-in `net/http` package can be configured to use the WASI HTTP interfaces. 12 | 13 | To do so, Golem's custom `Roundtrip` implementation hast to be used. 14 | This can be done directly before making http requests: 15 | 16 | ```go 17 | import ( 18 | "net/http" 19 | 20 | "github.com/golemcloud/golem-go/roundtrip" 21 | ) 22 | 23 | http.DefaultClient.Transport = roundtrip.WasiHttpTransport{}; 24 | ``` 25 | 26 | Or the convenience std package can be used at the start of component methods (which can also initialize commandline arguments and environment variable): 27 | 28 | ```go 29 | package main 30 | 31 | import ( 32 | "fmt" 33 | "net/http" 34 | "os" 35 | 36 | // import the std helper 37 | "github.com/golemcloud/golem-go/std" 38 | 39 | goexampleapi "golem/demo/go_example/bindings/go/example-example/go-example-api" 40 | ) 41 | 42 | func HelloWorld() string { 43 | // initialize the standard library's os and http package from the golem environment 44 | // this initialization has to be called at the start of the implementation methods 45 | std.Init(std.Packages{ 46 | Os: true, 47 | NetHttp: true, 48 | }) 49 | 50 | // The standard http package can be used to make http requests 51 | _, _ = http.Get("https://host/endpoint") 52 | 53 | return "Hello, World!" 54 | } 55 | 56 | func init() { 57 | goexampleapi.SetGoExample(goexampleapi.NewGoExampleImpl()) 58 | } 59 | ``` 60 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the Go development environment](/go-language-guide/setup) and learning the basic steps [writing a Golem component](/go-language-guide/defining-components) and [building them](/go-language-guide/building-components), please consider learning about the following topics: 6 | 7 | 8 | ### Making HTTP requests from a Golem component 9 | Learn how to [send HTTP requests from a Golem component written in Go](/go-language-guide/http). 10 | 11 | ### Control durability guarantees 12 | 13 | Check how the Go Golem SDK can [control various durability settings](/go-language-guide/durability) of Golem. 14 | 15 | ### Automatic retries 16 | 17 | Learn about Golem's retry mechanism and [how it can be customized](/go-language-guide/retries). 18 | 19 | ### Transactions 20 | 21 | Use the higher level [transactions library](/go-language-guide/transactions) to implement the _Saga pattern_. 22 | 23 | ### Promises 24 | 25 | Create and use [promises](/go-language-guide/promises) to await external events from within a running worker. 26 | 27 | ### Using WASI interfaces 28 | 29 | See what low-level [WASI interfaces](/go-language-guide/wasi) are available and how they can be used from Go. 30 | 31 | ### Call other workers from a worker 32 | 33 | [Worker to Worker communication](/common-language-guide/rpc) 34 | 35 | ### Set up the worker's filesystem 36 | 37 | [Worker filesystem](/common-language-guide/worker-filesystem) 38 | 39 | ### Share WIT packages between components 40 | 41 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 42 | 43 | ### Use LLMs 44 | 45 | [LLMs](/common-language-guide/llm) 46 | 47 | ### Use fork to achieve parallelism 48 | 49 | [Forking Workers](/common-language-guide/forking) 50 | 51 | 52 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/promises.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Working with Golem Promises in Go 4 | 5 | 6 | Check the [page about setting up the Golem Go SDK](/go-language-guide/golem-go-sdk) to make sure the SDK is available in your component. 7 | 8 | 9 | Golem **promises** provide a way for Golem workers to wait on an external condition. The worker creates the promise and somehow sends its identifier to the external system responsible for **completing** the promise. Then the worker can **await** the promise, being suspended until the external system completes the promise using Golem's REST API. 10 | 11 | It is also possible to complete a promise from within a Golem worker using the Golem SDK. 12 | 13 | When a promise is completed, an arbitrary byte array can be attached to it as a payload - this data is returned to the awaiting worker when is continues execution. 14 | 15 | In Go the promise API has idiomatic Go wrappers in the [Golem Go SDK](/go-language-guide/golem-go-sdk). 16 | 17 | ### Creating a promise 18 | 19 | To create a promise simply call the `golemhost.NewPromise` function: 20 | 21 | ```go 22 | import "github.com/golemcloud/golem-go/golemhost" 23 | 24 | promiseID := golemhost.NewPromise() 25 | ``` 26 | 27 | The returned value has the type `golemhost.PromiseID`, is defined as the following (including the nested types): 28 | 29 | ```go 30 | // UUID, uses the commonly used google UUID module 31 | type ComponentID uuid.UUID 32 | 33 | // Represents a Golem component 34 | typedef struct golem_api_host_component_id_t { 35 | golem_api_host_uuid_t uuid; 36 | } golem_api_host_component_id_t; 37 | 38 | // Represents a Golem worker 39 | type WorkerID struct { 40 | ComponentID ComponentID 41 | WorkerName string 42 | } 43 | 44 | // A promise ID is a value that can be passed to an external Golem API to complete that promise 45 | // from an arbitrary external source, while Golem workers can await for this completion. 46 | type PromiseID struct { 47 | WorkerID WorkerID 48 | OplogIdx OpLogIndex 49 | } 50 | ``` 51 | 52 | ### Deleting a promise 53 | 54 | If a promise is no longer used, it has to be deleted with: 55 | 56 | ```go 57 | import "github.com/golemcloud/golem-go/golemhost" 58 | 59 | golemhost.DeletePromise(promiseID) 60 | ``` 61 | 62 | ### Awaiting a promise 63 | 64 | To await a promise, use the `golemhost.AwaitPromise` or the `golemhost.AwaitPromiseJSON()` functions: 65 | 66 | ```go 67 | import "github.com/golemcloud/golem-go/golemhost" 68 | 69 | // returns the raw payload as []byte 70 | bs := golemhost.AwaitPromise(promiseID) 71 | 72 | type ExmaplePayload struct { 73 | ID int64 `json:"id"` 74 | Meta string `json:"meta,omitempty"` 75 | } 76 | var payload ExmaplePayload 77 | // requires a JSON unmarshall target and might return serialization errors 78 | err := golemhost.AwaitPromiseJSON(promiseID, &payload) 79 | ``` 80 | 81 | ### Completing a promise from within a worker 82 | 83 | To complete a promise from within a worker, use the `golemhost.CompletePromise` of the `golemhost.CompletePromiseJSON` functions: 84 | 85 | ```go 86 | import "github.com/golemcloud/golem-go/golemhost" 87 | 88 | // accepts the payload as []byte 89 | ok := golemhost.CompletePromise(promiseID, []byte{1, 2}) 90 | 91 | type ExmaplePayload struct { 92 | ID int64 `json:"id"` 93 | Meta string `json:"meta,omitempty"` 94 | } 95 | // accepts the payload as any JSON marshallable, and might return serialization errors 96 | ok, err := golemhost.CompletePromiseJSON( 97 | promiseID, 98 | ExmaplePayload{ 99 | ID: 100, 100 | Meta: "meta data", 101 | }, 102 | ) 103 | ``` 104 | 105 | ### Completing a promise from an external source 106 | 107 | To see how to use the **promise ID** to complete a promise through the external REST API, check [the REST API documentation](/rest-api). 108 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/retries.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Control the retry policy from Go 4 | 5 | 6 | Check the [page about setting up the Golem Go SDK](/go-language-guide/golem-go-sdk) to make sure the SDK is available in your component. 7 | 8 | 9 | ### Using Golem's retry mechanism 10 | 11 | Golem applies a retry mechanism to all workers. In case of a failure, Golem will automatically recover the worker to the point before the failure and retry the operation. An exponential backoff and an upper limit on the number of retries are applied. 12 | 13 | If the maximum number of retries is reached, the worker will be marked as failed and no further invocations will be possible on it. 14 | 15 | This mechanism is automatic and applied to all kind of failures. To rely on it, just let the Go code panic. 16 | 17 | ### Customizing the retry policy 18 | 19 | The retry policy which controls the maximum number of retries and the exponential backoff is a global configuration of the Golem servers, but it can be customized for each worker. 20 | 21 | The `golem-go` library provides the `golemhost.SetRetryPolicy` and `golemhost.WithRetryPolicy` functions to temporarily change the retry policy: 22 | 23 | ```go 24 | import ( 25 | "time" 26 | 27 | "github.com/golemcloud/golem-go/golemhost" 28 | ) 29 | 30 | // Setting directly the retry policy 31 | golemhost.SetRetryPolicy(golemhost.RetryPolicy{ 32 | MaxAttempts: 10, 33 | MinDelay: 100 * time.Millisecond, 34 | MaxDelay: 5 * time.Second, 35 | Multiplier: 3, 36 | MaxRetryFactor: nil, 37 | }) 38 | 39 | // WithRetryPolicy stores (using golemhost.GetRetryPolicy) the current retry policy and 40 | // then restores it after running the provided function 41 | result, err = golemhost.WithRetryPolicy( 42 | golemhost.RetryPolicy{ 43 | MaxAttempts: 4, 44 | MinDelay: 300 * time.Millisecond, 45 | MaxDelay: 3 * time.Second, 46 | Multiplier: 2, 47 | MaxRetryFactor: nil, 48 | }, 49 | func() (string, error) { 50 | return "golem", nil 51 | }, 52 | ) 53 | ``` 54 | 55 | The `golemhost.RetryPolicy` type itself is originated from Golem's WIT definition in the following way: 56 | 57 | ```wit 58 | /// Configures how the executor retries failures 59 | record retry-policy { 60 | /// The maximum number of retries before the worker becomes permanently failed 61 | max-attempts: u32, 62 | /// The minimum delay between retries (applied to the first retry) 63 | min-delay: duration, 64 | /// The maximum delay between retries 65 | max-delay: duration, 66 | /// Multiplier applied to the delay on each retry to implement exponential backoff 67 | multiplier: f64, 68 | /// The maximum amount of jitter to add to the delay 69 | max-jitter-factor: option 70 | } 71 | ``` 72 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | import { MultiPlatformCommand } from "@/components/multi-platform-command" 4 | 5 | # Setup Go 6 | 7 | Creating **Golem components** in **Go** requires using the latest version of the [TinyGo compiler](https://tinygo.org) and installing some common WebAssembly tooling. 8 | 9 | ## Installing TinyGo 10 | 11 | Use the [official guide](https://tinygo.org/getting-started/install/) to install the latest **stable** version of the TinyGo compiler. 12 | 13 | 14 | Note that TinyGo also requires Go to be installed too. Follow the recommended steps 15 | [here](https://go.dev/doc/install) to download and install the **latest** recommended version. 16 | 17 | 18 | 19 | For MacOS TinyGo can be installed using `brew`: 20 | 21 | ```bash 22 | brew tap tinygo-org/tools 23 | brew install tinygo 24 | ``` 25 | 26 | 27 | 28 | The minimum versions assumed by the documentation and templates are the following: 29 | - TinyGo: 0.37.0 30 | - Go: 1.24.0 31 | 32 | 33 | ## Install WebAssembly tooling 34 | 35 | You will need both `wasm-tools` and `wit-bindgen` to work on Go WebAssembly projects. 36 | Consult the [dedicated page](/installing-webassembly-tooling) for instructions on how to install them. 37 | 38 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/updating.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Updating workers to newer versions of Go components 5 | 6 | As described in the general [Workers](/concepts/workers) page, each worker runs on a specific version of the component it is based on, but it is possible to **update** a worker to a different version of the same component. 7 | 8 | ## Automatic update 9 | 10 | The **automatic update** mode has no Go-specific details and works as it is described in the general [Workers](/concepts/workers) page. 11 | 12 | ## Manual snapshot-based update 13 | 14 | Sometimes the change between two component versions is so large that the only solution to migrate worker's state to a new version is to manually implement this state transfer. 15 | 16 | This is done by implementing a `save-snapshot` function in the old component and a `load-snapshot` function in the new component. The snapshot is an array of bytes and it is the responsibility of the user to ensure that the snapshot is compatible between the two versions. 17 | 18 | These functions are defined in the `golem:api` WIT package and must be explicitly exported from the component's `world`. 19 | -------------------------------------------------------------------------------- /src/pages/go-language-guide/wasi.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Using WASI interfaces from Go 4 | 5 | Golem implements and exports a subset of the [WASI](https://wasi.dev) interfaces, as well as its own **runtime interfaces**. 6 | 7 | The [Golem Go SDK](/go-language-guide/golem-go-sdk) provides idiomatic wrappers on a subset of these interfaces, but it is also possible to use the generated bindings directly. 8 | 9 | ## WIT specifications 10 | 11 | The full set of WIT specifications Golem implements is available in the following public repository: 12 | 13 | https://github.com/golemcloud/golem-wit/tree/main/wit/deps 14 | 15 | The following table lists all packages provided by Golem: 16 | 17 | | Package | Description | 18 | | ----------------- | ------------------------------------------------------------------------------------------- | 19 | | `golem:api` | Golem's Runtime API | 20 | | `golem:rpc` | Provides support for Worker to Worker communication | 21 | | `wasi:blobstore` | Interface for storing and retrieving large binary data | 22 | | `wasi:cli` | Interface for environment variables and standard I/O | 23 | | `wasi:clocks` | Interface for querying the system time | 24 | | `wasi:filesystem` | Interface for working with files and directories | 25 | | `wasi:http` | Interface for making HTTP requests | 26 | | `wasi:io` | Interface for working with futures and streams | 27 | | `wasi:keyvalue` | Interface for storing and retrieving key-value pairs - only partially implemented | 28 | | `wasi:logging` | Interface for logging messages | 29 | | `wasi:random` | Interface for generating random numbers | 30 | | `wasi:sockets` | Interface for working with TCP and UDP sockets (currently not supporting durable execution) | 31 | 32 | ## Additional Golem runtime APIs 33 | 34 | This section describes Golem-specific functionalities which are available through the Golem runtime API but does not have an idiomatic Go wrapper in the `golem-go` library yet. 35 | 36 | ### The WASI Blob Store interface 37 | 38 | The `wasi:blobstore` interface provides a way to store and retrieve large binary data. This can be useful for storing large files or other binary data that is too large to be stored in the worker's memory. 39 | -------------------------------------------------------------------------------- /src/pages/http-api-definitions.mdx: -------------------------------------------------------------------------------- 1 | # API Definition Reference 2 | 3 | Learn more about API definition bindings here: 4 | 5 | - [API definition binding types](/http-api-definitions/api-definition-bindings.mdx) 6 | -------------------------------------------------------------------------------- /src/pages/index.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Card, Cards } from "nextra/components" 3 | import { 4 | Code, 5 | Cog, 6 | Gamepad, 7 | LibraryBig, 8 | Terminal, 9 | ArrowUpDown, 10 | SquareFunction, 11 | HardHat, 12 | CircleHelp, 13 | Rocket, 14 | } from "lucide-react" 15 | import { GolemIcon } from "src/components/golem-logo" 16 | 17 | # Golem Developer Documentation 18 | 19 | Welcome to the Golem developer documentation portal! Here you will find comprehensive documentation on how to build, deploy, and manage applications on Golem. 20 | 21 | 22 |
23 | Golem is available in both an open source version that you can deploy yourself and a hosted 24 | version that we manage for you. This documentation covers both versions, and we will discuss any 25 | differences between the two. 26 |
27 | 28 | 29 | ### Getting Started 30 | 31 | 32 | } /> 33 | } /> 34 | } /> 35 | 36 | 37 | ### Quick Links 38 | 39 | 40 | } /> 41 | } /> 42 | } /> 43 | } /> 44 | } /> 45 | } /> 46 | 47 | -------------------------------------------------------------------------------- /src/pages/invoke.mdx: -------------------------------------------------------------------------------- 1 | # Invoke workers 2 | 3 | Learn how to invoke [workers](/concepts/workers) using: 4 | 5 | - The [HTTP API](invoke/http) 6 | - The [CLI](invoke/cli) 7 | - By mapping to a [custom API](invoke/making-custom-apis) 8 | -------------------------------------------------------------------------------- /src/pages/invoke/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "http": "HTTP", 3 | "cli": "CLI", 4 | "repl": "REPL", 5 | "making-custom-apis": "Making Custom APIs" 6 | } 7 | -------------------------------------------------------------------------------- /src/pages/invoke/cli.mdx: -------------------------------------------------------------------------------- 1 | # Invoke using Golem CLI 2 | 3 | The `golem` command line interface exposes one invocation subcommand: 4 | 5 | - `golem worker invoke` triggers a function invocation on a worker and awaits its result 6 | - `golem worker invoke --enqueue` just enqueues an invocation and returns immediately 7 | 8 | ## Specifying what to invoke 9 | 10 | The command requires specifying which worker to invoke, and the name of the function. 11 | 12 | There are multiple options for selecting the worker: 13 | 14 | **Durable workers identified by a component ID and a worker name**: 15 | 16 | - `worker-name` 17 | - `component-name/worker-name` 18 | - `project-name/component-name/worker-name` 19 | - `account-name/project-name/component-name/worker-name` 20 | 21 | **Ephemeral workers identified by just a component**: 22 | 23 | - `-` 24 | - `component-name/-` 25 | - `project-name/component-name/-` 26 | - `account-name/project-name/component-name/-` 27 | 28 | Note that you can only omit the component name if it can be inferred from the context, for example if the current directory is a component directory or the application root with a single component only. 29 | 30 | The function to be invoked is selected by the second parameter. Read the [invocation function name syntax page](/function-names) for more information about the possible function names. 31 | 32 | ## Encoding parameters 33 | 34 | The CLI requires you to encode the function parameters using the [WebAssembly Value Encoding](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-wave) with one or more parameters following the function name (one for each invocation parameter). 35 | 36 | ## Getting results 37 | 38 | When using `invoke` without the `--enqueue` flag, the CLI awaits the result of the invocation and prints the result value to the standard output. By default it uses the `text` format, in which case it prints the result value using the [WebAssembly Value Encoding](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-wave). 39 | 40 | This can be changed with `--format json` or `--format yaml` to print the invocation result in JSON or YAML, using the [mapping described on the JSON WAVE Mapping page](/json-wave-mapping). 41 | 42 | ## Logs 43 | 44 | Both invocation commands accept an optional `--connect` flag for conneting to the invoked worker's event stream and showing its logs. This works the same as running a separate `golem worker connect` command during the invocation. The logs consists of everything the worker writes to its standard output and standard error, as well as through the WASI Logging API. 45 | 46 | The `--connect` option's output (and also the `connect` subcommand) can be customized with the following parameters: 47 | 48 | - `--format text|json|yaml` for different encodings of the log lines 49 | - `--colors=yes|no` to enable/disable colors for the `text` format 50 | - `--show-timestamps=yes|no` to enable/disable showing timestamps for each log line 51 | - `--show-level=yes|no` to enable/disable showing the log level (or stdout/stderr) for each log line 52 | 53 | ## Cancelling pending invocations 54 | 55 | As invocations are executed sequentially, it is possible to cancel a pending invocation before it starts executing. This can be done using the command line interface by running the `worker cancel-invocation` subcommand: 56 | 57 | ```shell copy 58 | golem worker cancel-invocation / --idempotency-key 59 | ``` 60 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis.mdx: -------------------------------------------------------------------------------- 1 | # Make Custom Http APIs for your Golem App 2 | 3 | Golem's [Gateway](/concepts/worker-gateway) service not only exposes the [low-level REST API for invocations](/invoke/http) 4 | but also provides a way to expose the worker functions as HTTP APIs. 5 | 6 | Future versions will support other protocols as well such as gRPC or GraphQL. 7 | 8 | For reference, see the [API Definition Reference](/http-api-definitions) page. 9 | 10 | ### API Development Workflow 11 | 12 | 1. **[Create a component](making-custom-apis/create-simple-component)**: Learn how to create a new API definition. 13 | 2. **[Expose HTTP APIs for your Golem App](making-custom-apis/expose-http-apis)**: Learn how to create a new API definition. 14 | 3. **[Update HTTP APIs](making-custom-apis/update-api-deployment)**: Make changes to existing APIs and redeploy. 15 | 4. **[Authenticated HTTP APIs APIs](making-custom-apis/authentication)**: Configure authentication mechanisms for your API. 16 | 5. **[CORS for HTTP APIs](making-custom-apis/cors)**: Set up Cross-Origin Resource Sharing (CORS) policies. 17 | 6. **[Customise Http Responses with Rib](making-custom-apis/rib-in-api-definition)**: Use Rib for customizing API response mappings. 18 | 7. **[Automatic Documentation for Endpoints](making-custom-apis/spec-inference)**: Learn more on automatic spec generation based on Rib scripts. 19 | 8. **[Constraints on Component Updates](making-custom-apis/component-constraints)**: Learn more on restrictions for updating components after deployment. 20 | 9. **[Import OpenAPI Specifications](making-custom-apis/import-openapi-spec)**: Convert OpenAPI specs into Golem API definitions. 21 | 10. **[Integrate with External API Gateways](making-custom-apis/external-api-gateways)**: Connect your APIs to existing gateways. 22 | 11. **[Troubleshoot Common Issues](making-custom-apis/trouble-shooting)**: Resolve potential problems with your APIs. 23 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "create-simple-component": "Create a simple component", 3 | "expose-http-apis": "Expose Http APIs", 4 | "try-out-deployed-api": "Invoke the deployed API", 5 | "update-api-deployment": "Update API definitions and deployments", 6 | "authentication": "Make APIs Secure", 7 | "cors": "Setting up CORS", 8 | "rib-in-api-definition": "Request Response Transformation using Rib", 9 | "import-openapi-spec": "Import OpenAPI Spec as API Definition", 10 | "external-api-gateways": "Integrating with external API Gateways", 11 | "component-constraints": "Constraints on Component updates after API deployment", 12 | "spec-inference": "Automatic API Spec Inference", 13 | "trouble-shooting": "Trouble Shooting" 14 | } 15 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis/component-constraints.mdx: -------------------------------------------------------------------------------- 1 | ## Constraints on Components after API deployment 2 | 3 | Please note that, once you have deployed an API using a specific component-version, then 4 | you may not be able to update the component-version (ex: `golem component deploy`) unless 5 | the arguments to the functions used in the Rib script in the deployed API definition is backward compatible. 6 | 7 | If there are conflicts (i.e, backward incompatible) then you will get a conflict report message, 8 | which details especially the missing functions and conflicting functions, where conflicting functions 9 | detail about existing parameter types, new parameter types, existing return type, and new return type. 10 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis/import-openapi-spec.mdx: -------------------------------------------------------------------------------- 1 | ## Support to import OpenAPI spec 2 | 3 | Until now, we used the native API definition format of Golem. 4 | Golem allows you to import API definition in OpenAPI spec format too. 5 | This is because, users may have already written an OpenAPI spec for their endpoints for various purposes. 6 | By adding extra details of into the same spec, we can use it as an API definition. Internally it gets converted to the Worker Gateway's native format of API definition, discussed in the beginning of this documentation. 7 | 8 | The main advantage of this feature is the re-usability of the same endpoint definitions across your system. For example, you can use the same file now to register with Golem's Worker Gateway and register with another external API gateway. More on this below. However once deployed, it returns native format then onwards, and updates needs to be done in the native format. 9 | 10 | ```yaml 11 | openapi: 3.0.0 12 | info: 13 | title: MyOpenAPISpec 14 | version: 1.0.2 15 | x-golem-api-definition-id: my-shopping-cart-v1 16 | x-golem-api-definition-version: 0.0.7 17 | paths: 18 | /{user-id}/get-cart-contents: 19 | get: 20 | x-golem-worker-bridge: 21 | component-id: dba38841-013a-49fa-a1dc-064949832f0c 22 | component-version: 0 23 | response: | 24 | let worker = instance("foo"); 25 | let x = worker.checkout(); 26 | let status: u64 = 200; 27 | let headers = {ContentType: "json", userid: "foo"}; 28 | let body = "foo"; 29 | {headers: headers, body: body, status: status} 30 | summary: Get Cart Contents 31 | description: Get the contents of a user's cart 32 | parameters: 33 | - name: user-id 34 | in: path 35 | required: true 36 | schema: 37 | type: string 38 | responses: 39 | 200: 40 | description: OK 41 | content: 42 | application/json: 43 | schema: 44 | $ref: "#/components/schemas/CartItem" 45 | 404: 46 | description: Contents not found 47 | components: 48 | schemas: 49 | CartItem: 50 | type: object 51 | properties: 52 | id: 53 | type: string 54 | name: 55 | type: string 56 | price: 57 | type: number 58 | ``` 59 | 60 | To import OpenAPI spec using Golem CLI, 61 | 62 | ```shell copy 63 | golem api definition import open_api.json 64 | ``` 65 | 66 | This will return 67 | 68 | ```json 69 | { 70 | "id": "my-shopping-cart-v1", 71 | "version": "0.0.7", 72 | "routes": [ 73 | { 74 | "method": "Get", 75 | "path": "/{user-id}/get-cart-contents", 76 | "binding": { 77 | "component": { 78 | "name": "my-shopping-cart", 79 | "version": 0 80 | }, 81 | "idempotencyKey": null, 82 | "response": "let worker = instance(\"foo\"); let x = worker.checkout();\nlet status: u64 = 200;\n{headers: {ContentType: \"json\", userid: \"foo\"}, body: \"foo\", status: status}", 83 | "responseMappingInput": { 84 | "types": {} 85 | }, 86 | "workerNameInput": { 87 | "types": {} 88 | }, 89 | "idempotencyKeyInput": null 90 | } 91 | } 92 | ], 93 | "draft": true, 94 | "createdAt": "2024-10-31T08:56:02.412860043Z" 95 | } 96 | ``` 97 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis/spec-inference.mdx: -------------------------------------------------------------------------------- 1 | ## Automatic Inference of required inputs for API Endpoint based on Rib script 2 | 3 | Now that, we registered API definitions, and deployed them. As you have seen Rib script in the response field or worker name 4 | may try to look up values from the request context. This is auto documented and you can see them in the response when you register an API definition 5 | Golem Console provides a more user-friendly way to see these inputs. 6 | 7 | Here is a sample response when you register an API definition, where it holds the required data in the input http request. 8 | 9 | ```json 10 | { 11 | "id": "my-shopping-cart-v1", 12 | "version": "0.0.4", 13 | "routes": [ 14 | { 15 | "method": "Get", 16 | "path": "/v4/{user-id}/get-cart-contents", 17 | "binding": { 18 | "component": { 19 | "name": "shopping-cart", 20 | "version": 0 21 | }, 22 | "workerName": "let user: u64 = request.path.user-id;\n\"my-worker-${user}\"", 23 | "idempotencyKey": null, 24 | "response": "let result = golem:it/api.{get-user-name}();\n{status: 200u64, body: result}", 25 | "responseMappingInput": { 26 | "types": { 27 | "request": { 28 | "type": "Record", 29 | "fields": [ 30 | { 31 | "name": "path", 32 | "typ": { 33 | "type": "Record", 34 | "fields": [ 35 | { 36 | "name": "user-id", 37 | "typ": { 38 | "type": "U64" 39 | } 40 | } 41 | ] 42 | } 43 | } 44 | ] 45 | } 46 | } 47 | }, 48 | "workerNameInput": { 49 | "types": { 50 | "request": { 51 | "type": "Record", 52 | "fields": [ 53 | { 54 | "name": "path", 55 | "typ": { 56 | "type": "Record", 57 | "fields": [ 58 | { 59 | "name": "user-id", 60 | "typ": { 61 | "type": "U64" 62 | } 63 | } 64 | ] 65 | } 66 | } 67 | ] 68 | } 69 | } 70 | }, 71 | "responseMappingOutput": { 72 | "type": "Record", 73 | "fields": [ 74 | { 75 | "name": "status", 76 | "typ": { 77 | "type": "U64" 78 | } 79 | }, 80 | { 81 | "name": "body", 82 | "typ": { 83 | "type": "Str" 84 | } 85 | } 86 | ] 87 | }, 88 | "idempotencyKeyInput": null 89 | } 90 | } 91 | ], 92 | "draft": true, 93 | "createdAt": "2024-10-31T07:40:16.239763054Z" 94 | } 95 | ``` 96 | 97 | In the above response, you can see the `responseMappingInput` field which holds the required input for the Rib script in the response field, 98 | as well as `workerNameInput` which holds the required input for the Rib script in the workerName field. 99 | 100 | ## Automatic inference of output types for API Endpoint based on Rib script 101 | 102 | In the same example above, it infers the output types of the response mapping Rib script as well. 103 | In near future, these auto inferred inputs and outputs can be used to generate OpenAPI spec for the 104 | API that is deployed in Golem. 105 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis/trouble-shooting.mdx: -------------------------------------------------------------------------------- 1 | ## Watch out for errors during deployment 2 | 3 | ### Route conflict errors during deployment 4 | 5 | Please note the following: If you already deployed an API definition before with the same path `/{user-id}/get-cart-contents`, 6 | then you will receive a conflict error as given below. 7 | 8 | ```bash filename="Terminal" copy 9 | API deployment definitions conflict error: /{user-id}/get-cart-contents 10 | ``` 11 | 12 | This implies, when you update the version, you have to update the path as well, such as `/v5/{user-id}/get-cart-contents` 13 | under the `path` field in `route`. 14 | 15 | ### Watch out for more errors during API definition and deployment updates 16 | 17 | Please read through how to [update API definitions and deployments](/invoke/making-custom-apis/update-api-deployment) 18 | to understand possible errors and how to manage them. 19 | 20 | ### BadRequest errors when invoking the API with inputs 21 | 22 | If your API's implementation (Rib script which internally calls workers) gets a wrong input (Example: wrong types in http request), 23 | it produces a `BadRequest`. This makes Golem Gateway much more type safe than a typical Gateway 24 | where it always routes to the backend regardless of wrong inputs. 25 | 26 | Here is an example: 27 | 28 | ```rib copy 29 | let user: u64 = request.path.user-id; 30 | let my-worker = instance("my-worker-${user}"); 31 | my-worker.add-cart(request.body.product); 32 | ``` 33 | 34 | Here we expect the request body to have a product field, with all the fields of the record type that `add-cart` function expects. 35 | If the request body is wrong, we get a bad request error as shown below. 36 | 37 | ```bash copy 38 | > 39 | * Request completely sent off 40 | < HTTP/1.1 400 Bad Request 41 | < access-control-allow-origin: * 42 | < content-length: 392 43 | < date: Tue, 10 Dec 2024 03:42:54 GMT 44 | < 45 | * Connection #1 to host localhost left intact 46 | Input request details don't match the requirements for rib expression to execute: Invalid value for the key path. 47 | Error: Invalid value for the key product. Error: Expected function parameter type is u64. But found string. 48 | Requirements. Record(TypeRecord { fields: [NameTypePair { name: "product-id", typ: U64)% 49 | 50 | ``` 51 | -------------------------------------------------------------------------------- /src/pages/invoke/making-custom-apis/try-out-deployed-api.mdx: -------------------------------------------------------------------------------- 1 | ## Use the deployed API 2 | 3 | Given, you have successfully deployed, now you can try to invoke the following: 4 | 5 | ```shell copy 6 | curl -H "Accept: application/json" -X GET http://localhost:9006/v4/100/get-cart-contents 7 | [] 8 | ``` 9 | 10 | Here the worker-gateway identifies the user to be `100` 11 | and evaluates the worker-name expr to be `my-worker-100` 12 | by evaluating `workerName` Rib expression. 13 | 14 | Once it identifies the worker-name, it goes on evaluating the `response` Rib expression which internally invokes the worker function function `golem:it/api.{get-cart-contents}` 15 | with empty parameters, and simply get the worker-response (which is a WASM value) 16 | and converts it to a proper Http Response. 17 | -------------------------------------------------------------------------------- /src/pages/invoke/repl.mdx: -------------------------------------------------------------------------------- 1 | ## Golem REPL 2 | 3 | Once you have a component using `golem app` commands, 4 | you can spin up a REPL to interact with your functions. 5 | 6 | Golem REPL is backed by the language [Rib](/rib) 7 | 8 | 9 | ```shell 10 | cd shopping-cart 11 | golem repl 12 | ``` 13 | 14 | ```shell 15 | >>> let worker = instance("worker") 16 | () 17 | 18 | >>> worker.add-item({product-id: "foo", name: "foo", price: 42, quantity: 42}) 19 | () 20 | 21 | >>> worker.add-item({product-id: "foo", name: "foo", price: 42, quantity: 42}) 22 | () 23 | 24 | >>> worker.get-cart-contents() 25 | [{product-id: "foo", name: "foo", price: 42, quantity: 42}, {product-id: "foo", name: "foo", price: 42, quantity: 42}] 26 | 27 | >>> worker.checkout() 28 | success({order-id: "238738674"}) 29 | ``` 30 | 31 | REPL is a great way to test the component and its functions, 32 | however note that it's a brand new feature and is experimental in nature. -------------------------------------------------------------------------------- /src/pages/js-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps", 10 | "-- golem-sdk": { 11 | "type": "separator", 12 | "title": "Golem SDK" 13 | }, 14 | "golem-js-sdk": "Setting up the Golem JS SDK", 15 | "http": "HTTP client", 16 | "durability": "Durability", 17 | "retries": "Retries", 18 | "transactions": "Transactions", 19 | "promises": "Promises", 20 | "updating": "Updating Workers", 21 | "wasi": "WASI" 22 | } 23 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in JavaScript 5 | 6 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 7 | 8 | ```shell copy 9 | golem app build 10 | ``` 11 | 12 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 13 | 14 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 15 | 16 | ```shell copy 17 | golem component add 18 | ``` 19 | 20 | ## Under the hood 21 | Building Golem components written in JavaScript requires a series of steps. 22 | 23 | If the project was created with `golem app new`, it already has a `package.json` that incorporates all the necessary steps as _npm scripts_ to build the component, so it is enough to run: 24 | 25 | ```shell copy 26 | npm run componentize 27 | ``` 28 | 29 | In details, building the component requires the following steps: 30 | 31 | 32 | ### Compile the JavaScript code to JavaScript 33 | 34 | The examples use `rollup` through an _npm script_: 35 | 36 | ```shell 37 | $ npm run build 38 | ``` 39 | 40 | This will compile all the _JavaScript_ sources into a **single** _JavaScript_ file at `out/main.js`. 41 | 42 | ### Componentizing the JavaScript code 43 | 44 | The final step is **componentizing**, which involves: 45 | 46 | - embedding our _JavaScript_ code into the _StarlingMonkey JS engine_ 47 | - running _Wizer pre-initialization_, which pre-loads and parses our Javascript source in the JS engine 48 | - creating the _wasm output_ file for our component with it's interface exposed as a _WebAssembly component_ usable by _Golem_. 49 | 50 | The example projects includes an _npm script_ called `componentize`, which also includes the previous `build` step. 51 | 52 | ```shell 53 | $ npm run componentize 54 | ``` 55 | 56 | The output wasm file with be created with the built component name, eg.: `out/example.wasm`. 57 | 58 | The above _npm script_ will execute the following commands: 59 | 60 | ``` 61 | $ npm run build && jco componentize -w wit -o out/example.wasm out/main.js 62 | ``` 63 | 64 | 65 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/golem-js-sdk.mdx: -------------------------------------------------------------------------------- 1 | import { Callout, Steps, Tabs } from "nextra/components" 2 | import { AllWitDeps } from "@/components/all-wit-deps" 3 | import { MultiPlatformCommand } from "@/components/multi-platform-command" 4 | 5 | # Setting up the Golem JavaScript SDK 6 | 7 | 8 | If the project was created with `golem new`, it already has the Golem JavaScript SDK set up 9 | and these steps can be ignored. 10 | 11 | 12 | 13 | The _Golem JavaScript SDK_ is the same as the _Golem TypeScript SDK_. The published SDK is usable 14 | from _JavaScript_, as it is bundled as JavaScript. 15 | 16 | 17 | To add the [Golem JavaScript SDK](https://github.com/golemcloud/golem-ts) to a project, just install it using npm; 18 | 26 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/http.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # HTTP requests in JavaScript 4 | 5 | Golem implements the [WASI HTTP](https://github.com/WebAssembly/wasi-http) interfaces so any library built on this specification can be used from Golem components to communicate with external services. 6 | HTTP request can also be made with the JavaScript standard builtin `fetch` function. 7 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the JavaScript development environment](/js-language-guide/setup) and learning the basic steps [writing a Golem component](/js-language-guide/defining-components) and [building them](/js-language-guide/building-components), please consider learning about the following topics: 6 | 7 | 8 | ### Making HTTP requests from a Golem component 9 | Learn how to [send HTTP requests from a Golem component written in JavaScript](/js-language-guide/http). 10 | 11 | ### Control durability guarantees 12 | 13 | Check how the JavaScript Golem SDK can [control various durability settings](/js-language-guide/durability) of Golem. 14 | 15 | ### Automatic retries 16 | 17 | Learn about Golem's retry mechanism and [how it can be customized](/js-language-guide/retries). 18 | 19 | ### Transactions 20 | 21 | Use the higher level [transactions library](/js-language-guide/transactions) to implement the _Saga pattern_. 22 | 23 | ### Promises 24 | 25 | Create and use [promises](/js-language-guide/promises) to await external events from within a running worker. 26 | 27 | ### Using WASI interfaces 28 | 29 | See what low-level [WASI interfaces](/js-language-guide/wasi) are available and how they can be used from JavaScript. 30 | 31 | ### Call other workers from a worker 32 | 33 | [Worker to Worker communication](/common-language-guide/rpc) 34 | 35 | ### Set up the worker's filesystem 36 | 37 | [Worker filesystem](/common-language-guide/worker-filesystem) 38 | 39 | ### Share WIT packages between components 40 | 41 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 42 | 43 | ### Use LLMs 44 | 45 | [LLMs](/common-language-guide/llm) 46 | 47 | ### Use fork to achieve parallelism 48 | 49 | [Forking Workers](/common-language-guide/forking) 50 | 51 | 52 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/promises.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Working with Golem Promises in JavaScript 4 | 5 | Golem **promises** provide a way for Golem workers to wait on an external condition. The worker creates the promise and somehow sends its identifier to the external system responsible for **completing** the promise. Then the worker can **await** the promise, being suspended until the external system completes the promise using Golem's REST API. 6 | 7 | It is also possible to complete a promise from within a Golem worker using the Golem SDK. 8 | 9 | When a promise is completed, an arbitrary byte array can be attached to it as a payload - this data is returned to the awaiting worker when is continues execution. 10 | 11 | In JavaScript the promise API has idiomatic JavaScript wrappers in the [Golem JavaScript SDK](/js-language-guide/golem-js-sdk). 12 | 13 | ### Creating a promise 14 | 15 | To create a promise simply call the `createPromise` function: 16 | 17 | ```javascript 18 | import { createPromise, PromiseId } from "@golemcloud/golem-ts" 19 | 20 | const promiseId = createPromise() 21 | ``` 22 | 23 | The returned value has the following shape: 24 | 25 | ```javascript 26 | // A promise ID is a value that can be passed to an external Golem API to complete that promise 27 | // from an arbitrary external source, while Golem workers can await for this completion. 28 | const promiseId = { 29 | // Represents the worker 30 | workerId: { 31 | // Represents the component 32 | componentId: { 33 | uuid: { 34 | highBits: BigInt(0), 35 | lowBits: BigInt(0), 36 | }, 37 | }, 38 | workerName: "worker-name", 39 | }, 40 | oplogIdx: BigInt(0), 41 | } 42 | ``` 43 | 44 | ### Deleting a promise 45 | 46 | If a promise is no longer used, it has to be deleted with: 47 | 48 | ```javascript 49 | import { deletePromise } from "@golemcloud/golem-ts" 50 | 51 | deletePromise(promiseId) 52 | ``` 53 | 54 | ### Awaiting a promise 55 | 56 | To await a promise, use the `awaitPromise` functions, which returns the promise result as a byte array payload. 57 | Here's an example that awaits a promise, then decodes the payload from JSON format: 58 | 59 | ```javascript 60 | import { awaitPromise } from "@golemcloud/golem-ts" 61 | 62 | const byteArrayPayload = awaitPromise(promiseId) // returns Uint8Array; 63 | const payload = JSON.parse(new TextDecoder().decode(byteArrayPayload)) 64 | ``` 65 | 66 | ### Completing a promise from within a worker 67 | 68 | To complete a promise from within a worker, use the `completePromise` function. 69 | The following example completes a promise with a value encoded as JSON: 70 | 71 | ```javascript 72 | import { completePromise } from "@golemcloud/golem-ts" 73 | 74 | const payload = { 75 | id: "value", 76 | meta: "data", 77 | } 78 | const byteArrayPayload = new TextEncoder().encode(JSON.stringify(payload)) // create Uint8Array payload; 79 | const success = completePromise(promiseId, byteArrayPayload) // returns boolean; 80 | ``` 81 | 82 | ### Completing a promise from an external source 83 | 84 | To see how to use the **promise ID** to complete a promise through the external REST API, check [the REST API documentation](/rest-api). 85 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/retries.mdx: -------------------------------------------------------------------------------- 1 | # Control the retry policy from JavaScript 2 | 3 | ### Using Golem's retry mechanism 4 | 5 | Golem applies a retry mechanism to all workers. In case of a failure, Golem will automatically recover the worker to the point before the failure and retry the operation. An exponential backoff and an upper limit on the number of retries are applied. 6 | 7 | If the maximum number of retries is reached, the worker will be marked as failed and no further invocations will be possible on it. 8 | 9 | This mechanism is automatic and applied to all kind of failures. To rely on it, just throw an unhandled exception. 10 | 11 | ### Customizing the retry policy 12 | 13 | The retry policy which controls the maximum number of retries and the exponential backoff is a global configuration of the Golem servers, but it can be customized for each worker. 14 | 15 | The `golem-ts` library exports the `withRetryPolicy` function to temporarily change the retry policy: 16 | 17 | ```typescript 18 | import { withRetryPolicy } from "@golemcloud/golem-ts" 19 | 20 | // Durations are expected as nanoseconds 21 | const result = withRetryPolicy( 22 | { 23 | maxAttempts: 3, 24 | minDelay: BigInt(100 * 1000 * 1000), // 100 milliseconds 25 | maxDelay: BigInt(2 * 1000 * 1000 * 1000), // 2 seconds 26 | multiplier: 1.5, 27 | maxJitterFactor: null, 28 | }, 29 | () => { 30 | // this closure runs with the custom retry policy 31 | return "hello" 32 | } 33 | ) 34 | ``` 35 | 36 | The `RetryPolicy` interface required by `withRetryPolicy` is generated from Golem's WIT definition: 37 | 38 | ```wit 39 | /// Configures how the executor retries failures 40 | record retry-policy { 41 | /// The maximum number of retries before the worker becomes permanently failed 42 | max-attempts: u32, 43 | /// The minimum delay between retries (applied to the first retry) 44 | min-delay: duration, 45 | /// The maximum delay between retries 46 | max-delay: duration, 47 | /// Multiplier applied to the delay on each retry to implement exponential backoff 48 | multiplier: f64, 49 | /// The maximum amount of jitter to add to the delay 50 | max-jitter-factor: option 51 | } 52 | ``` 53 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | ## Setup development environment for JavaScript 5 | 6 | Golem's JavaScript toolchain is using npm as the underlying build tool. 7 | Install **Node.js** and **npm** to your system by following the official [instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). 8 | -------------------------------------------------------------------------------- /src/pages/js-language-guide/updating.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Updating workers to newer versions of JavaScript components 5 | 6 | As described in the general [Workers](/concepts/workers) page, each worker runs on a specific version of the component it is based on, but it is possible to **update** a worker to a different version of the same component. 7 | 8 | ## Automatic update 9 | 10 | The **automatic update** mode has no JavaScript-specific details and works as it is described in the general [Workers](/concepts/workers) page. 11 | 12 | ## Manual snapshot-based update 13 | 14 | Sometimes the change between two component versions is so large that the only solution to migrate worker's state to a new version is to manually implement this state transfer. 15 | 16 | This is done by implementing a `save-snapshot` function in the old component and a `load-snapshot` function in the new component. The snapshot is an array of bytes and it is the responsibility of the user to ensure that the snapshot is compatible between the two versions. 17 | 18 | These functions are defined in the `golem:api` WIT package and must be explicitly exported from the component's `world`. 19 | -------------------------------------------------------------------------------- /src/pages/operate/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "persistence": "Persistence", 3 | "metrics": "Metrics", 4 | "logs": "Logs", 5 | "metadata": "Metadata", 6 | "invocation_context": "Invocation Context" 7 | } 8 | -------------------------------------------------------------------------------- /src/pages/operate/invocation_context.mdx: -------------------------------------------------------------------------------- 1 | # Invocation Context 2 | 3 | Golem associates an **invocation context** with each worker invocation. This invocation context consists of a stack of **spans**, each having a collection of **attributes**. Currently only string attributes are supported. 4 | 5 | The invocation context can be queried and manipulated (by adding custom spans with custom attributes) using [Golem specific host functions](/golem-host-functions). 6 | 7 | By default the invocation context's spans are not used by Golem for anything - it is just information propagated among workers to be used by either the workers, or **oplog processor plugins** installed to them. It is possible to reconstruct all information about invocation context from the oplog, so oplog processor plugins can be used for example to provide live traces of workers through OpenTelemetry. 8 | 9 | ## Automatic invocation context spans 10 | 11 | ### Incoming HTTP requests 12 | The root spans of an invocation are containing information depending on how that invocation was started. When invoking through the [invocation REST API](/invoke/http), [W3C Trace Context](https://www.w3.org/TR/trace-context/) headers are automatically processed to set the root **trace-id** and **parent span-id**. 13 | 14 | When using [custom APIs](/invoke/making-custom-apis), the same headers are also taken into account by default, but it is also possible to write a **custom Rib script** per endpoint to extract more information from the HTTP requests and define custom **span attributes** with them. 15 | 16 | In both cases, when the invocation's trigger is a HTTP request, a spans is added with the following attributes: 17 | 18 | - `request.method` 19 | - `request.uri` 20 | - `request.remote_addr` 21 | 22 | ### Invocations 23 | When an invocation reaches a worker, a new span is created containing the following attributes: 24 | 25 | - `name`: span's name (`invoke-exported-function`) 26 | - `idempotency_key`: unique identifier of the invocation 27 | - `function_name`: the fully qualified function name 28 | - `worker_id`: worker's id (consists of component ID and worker name) 29 | 30 | ### Outgoing HTTP requests 31 | Outgoing HTTP requests are also represented by their own automatic spans with the following attributes: 32 | 33 | - `name`: span's name (`outgoing-http-request`) 34 | - `request.method`: the outgoing request's HTTP method 35 | - `request.uri`: the outgoing request's URI 36 | 37 | ### RPC calls 38 | RPC calls on the caller side are also represented by a custom spans. First a span is created when the underlying RPC resource is initialized, with the following attributes: 39 | 40 | - `name`: span's name (`rpc-connection`) 41 | - `target_worker_id`: the target worker's ID 42 | 43 | Within this span, a new span is created for each remote invocation, with the following attributes: 44 | 45 | - `name`: span's name (`rpc-invocation`) 46 | - `function_name`: the invoked function's fully qualified name 47 | - `idempotency_key`: the unique identifier of the invocation 48 | -------------------------------------------------------------------------------- /src/pages/operate/metadata.mdx: -------------------------------------------------------------------------------- 1 | # Metadata 2 | 3 | Services are using following types of storage: 4 | 5 | - Relational Database (RDB) - [PostgreSQL](https://www.postgresql.org/) or SQLite (mainly for testing purposes) 6 | - [Redis](https://redis.io/) 7 | - Blob storage - Shared File System or S3 8 | 9 | ### Component Service 10 | 11 | Service is using RDB and Blob storage as data storage. 12 | 13 | RDB tables: 14 | 15 | | Table | Description | 16 | | -------------------- | -------------------------------------------------------------- | 17 | | `components` | Components data - id, name | 18 | | `component_versions` | Version specific components data - version, component metadata | 19 | 20 | See [RDB migrations](https://github.com/golemcloud/golem/blob/main/golem-component-service/db/migration) for more details. 21 | 22 | Blob storage is used to store [components](/concepts/components) binary data. 23 | 24 | ### Worker Service 25 | 26 | Service is using RDB as data storage. 27 | 28 | RDB tables: 29 | 30 | | Table | Description | 31 | | ----------------- | -------------------- | 32 | | `api_definitions` | API definitions data | 33 | | `api_deployments` | API deployments data | 34 | 35 | See [RDB migrations](https://github.com/golemcloud/golem/blob/main/golem-worker-service/db/migration) for more details. 36 | 37 | ### Shard Manager 38 | 39 | Service is using Redis as data storage. Redis is used to store shard assignments. 40 | Shard assignments are stored in one record with key `shard:shard_manager_state`. 41 | 42 | ### Component Compilation Service 43 | 44 | Service is using Blob storage as data storage. 45 | 46 | ### Worker Executor 47 | 48 | See the [persistence](/operate/persistence) page for more details about how the worker state get persisted. 49 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps", 10 | "-- golem-sdk": { 11 | "type": "separator", 12 | "title": "Golem SDK" 13 | }, 14 | "http": "HTTP client", 15 | "durability": "Durability", 16 | "retries": "Retries", 17 | "promises": "Promises", 18 | "updating": "Updating Workers", 19 | "wasi": "WASI" 20 | } 21 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in Python 5 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 6 | 7 | ```shell copy 8 | golem app build 9 | ``` 10 | 11 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 12 | 13 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 14 | 15 | ```shell copy 16 | golem component add 17 | ``` 18 | 19 | ## Under the hood 20 | Building Golem components written in Python involves two steps: 21 | 22 | 23 | 24 | ### Package the Python code into a WASM component 25 | 26 | The `componentize` subcommand of the `componentize-py` tool packages the Python code and the Python interpreter into a single WebAssembly component: 27 | 28 | ```shell 29 | $ componentize-py componentize main -o py_example.wasm 30 | ``` 31 | 32 | 33 | Note that the `componentize-py` tool respects the `VIRTUAL_ENV` environment variable, so make sure 34 | to activate the virtualenv if there are any Python dependencies used by your component. 35 | 36 | 37 | ### Reducing the size of the component 38 | 39 | The output of `compoenntize-py` is large. It is possible to strip some parts of it to reduce the size by about 50% using the `wasm-tools strip` command: 40 | 41 | ```shell 42 | $ wasm-tools strip -a py_example.wasm -o py_example_stripped.wasm 43 | ``` 44 | 45 | ### Generate the Python bindings from the WIT files 46 | 47 | The `bindings` subcommand of the `componentize-py` tool generates the module containing the generated bindings: 48 | 49 | ```shell 50 | $ componentize-py bindings generated_bindings 51 | ``` 52 | 53 | This will generate bindings into the `bindings` directory. 54 | Make sure to not actually use these bindings to **invoke** imported functions, as they don't have any implementation. 55 | 56 | 57 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/http.mdx: -------------------------------------------------------------------------------- 1 | # HTTP requests in Python 2 | 3 | Golem implements the [WASI HTTP](https://github.com/WebAssembly/wasi-http) interfaces so any library built on this specification can be used from Golem components to communicate with external services. 4 | 5 | The only way to make HTTP requests from Python code currently is to use these WASI HTTP interfaces directly. 6 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the Python development environment](/python-language-guide/setup) and learning the basic steps [writing a Golem component](/python-language-guide/defining-components) and [building them](/python-language-guide/building-components), please consider learning about the following topics: 6 | 7 | 8 | ### Making HTTP requests from a Golem component 9 | Learn how to [send HTTP requests from a Golem component written in Python](/python-language-guide/http). 10 | 11 | ### Control durability guarantees 12 | 13 | Check how the Golem runtime API can [control various durability settings](/python-language-guide/durability) of Golem. 14 | 15 | ### Automatic retries 16 | 17 | Learn about Golem's retry mechanism and [how it can be customized](/python-language-guide/retries). 18 | 19 | ### Promises 20 | 21 | Create and use [promises](/python-language-guide/promises) to await external events from within a running worker. 22 | 23 | ### Using WASI interfaces 24 | 25 | See what low-level [WASI interfaces](/python-language-guide/wasi) are available and how they can be used from Python. 26 | 27 | ### Call other workers from a worker 28 | 29 | [Worker to Worker communication](/common-language-guide/rpc) 30 | 31 | ### Set up the worker's filesystem 32 | 33 | [Worker filesystem](/common-language-guide/worker-filesystem) 34 | 35 | ### Share WIT packages between components 36 | 37 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 38 | 39 | ### Use LLMs 40 | 41 | [LLMs](/common-language-guide/llm) 42 | 43 | ### Use fork to achieve parallelism 44 | 45 | [Forking Workers](/common-language-guide/forking) 46 | 47 | 48 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/promises.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Working with Golem Promises in Python 4 | 5 | Golem **promises** provide a way for Golem workers to wait on an external condition. The worker creates the promise and somehow sends its identifier to the external system responsible for **completing** the promise. Then the worker can **await** the promise, being suspended until the external system completes the promise using Golem's REST API. 6 | 7 | It is also possible to complete a promise from within a Golem worker using the Golem SDK. 8 | 9 | When a promise is completed, an arbitrary byte array can be attached to it as a payload - this data is returned to the awaiting worker when is continues execution. 10 | 11 | In Python the promise API can be used by directly importing and using the Golem runtime API. 12 | 13 | ### Adding as a dependency 14 | 15 | To use Golem's runtime API, add all the WIT files from https://github.com/golemcloud/golem-wit/tree/main/wit/deps in the project's `wit/deps` directory, and then importing this interface to the component's world: 16 | 17 | ```wit 18 | world example { 19 | import golem:api/host@1.1.0; 20 | // ... 21 | } 22 | ``` 23 | 24 | 25 | The `golem new` examples for Python automatically create the `wit/deps` directory for you, 26 | except the `c-actor-minimal` one. 27 | 28 | 29 | ### Creating a promise 30 | 31 | To create a promise simply call the `create_promise` function: 32 | 33 | ```python 34 | from py_example.imports.host import create_promise 35 | 36 | promise_id = create_promise() 37 | ``` 38 | 39 | The returned value, `PromiseId`, is defined as the following: 40 | 41 | ```python 42 | @dataclass 43 | class Uuid: 44 | """ 45 | UUID 46 | """ 47 | high_bits: int 48 | low_bits: int 49 | 50 | @dataclass 51 | class ComponentId: 52 | """ 53 | Represents a Golem component 54 | """ 55 | uuid: Uuid 56 | 57 | @dataclass 58 | class WorkerId: 59 | """ 60 | Represents a Golem worker 61 | """ 62 | component_id: ComponentId 63 | worker_name: str 64 | 65 | @dataclass 66 | class PromiseId: 67 | """ 68 | A promise ID is a value that can be passed to an external Golem API to complete that promise 69 | from an arbitrary external source, while Golem workers can await for this completion. 70 | """ 71 | worker_id: WorkerId 72 | oplog_idx: int 73 | ``` 74 | 75 | ### Deleting a promise 76 | 77 | If a promise is no longer used, it has to be deleted with 78 | 79 | ```python 80 | delete_promise(promise_id); 81 | ``` 82 | 83 | ### Awaiting a promise 84 | 85 | To await a promise, use the `await_promise` function: 86 | 87 | ```python 88 | payload = await_promise(promise_id) 89 | ``` 90 | 91 | The resulting `payload` is a byte array (`bytes`) containig the data attached to the promise on completion. 92 | 93 | ### Completing a promise from within a worker 94 | 95 | To complete a promise from within a worker, use the `complete_promise` function: 96 | 97 | ```python 98 | complete_promise(promise_id, str.encode("hello world")) 99 | ``` 100 | 101 | ### Completing a promise from an external source 102 | 103 | To see how to use the **promise ID** to complete a promise through the external REST API, check [the REST API documentation](/rest-api). 104 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/retries.mdx: -------------------------------------------------------------------------------- 1 | # Control the retry policy from Python 2 | 3 | ### Using Golem's retry mechanism 4 | 5 | Golem applies a retry mechanism to all workers. In case of a failure, Golem will automatically recover the worker to the point before the failure and retry the operation. An exponential backoff and an upper limit on the number of retries are applied. 6 | 7 | If the maximum number of retries is reached, the worker will be marked as failed and no further invocations will be possible on it. 8 | 9 | This mechanism is automatic and applied to all kind of failures. To rely on it, just let the Python code fail (raise an exception). 10 | 11 | ### Customizing the retry policy 12 | 13 | The retry policy which controls the maximum number of retries and the exponential backoff is a global configuration of the Golem servers, but it can be customized for each worker. 14 | 15 | Once the `golem:api/host@1.1.0` interface is imported in the WIT file (see the [previous page for more information](/python-language-guide/durability)), the retry policy can be controlled with the `get_retry_policy` and `set_retry_policy` functions. 16 | 17 | ```python 18 | import py_example 19 | import py_example.imports 20 | import py_example.imports.types 21 | import py_example.imports.host 22 | import py_example.exports 23 | import py_example.exports.api 24 | from py_example.imports.host import get_retry_policy, set_retry_policy, RetryPolicy 25 | 26 | old = get_retry_policy() 27 | try: 28 | set_retry_policy(RetryPolicy(max_attempts=10, min_delay=1_000_000_000, max_delay=1_000_000_000, multiplier=1)) 29 | # ... 30 | finally: 31 | set_retry_policy(old) 32 | // ... 33 | 34 | golem_api_host_get_retry_policy(&previous); 35 | ``` 36 | 37 | The `RetryPolicy` type itself is originated from Golem's WIT definition in the following way: 38 | 39 | ```wit 40 | /// Configures how the executor retries failures 41 | record retry-policy { 42 | /// The maximum number of retries before the worker becomes permanently failed 43 | max-attempts: u32, 44 | /// The minimum delay between retries (applied to the first retry) 45 | min-delay: duration, 46 | /// The maximum delay between retries 47 | max-delay: duration, 48 | /// Multiplier applied to the delay on each retry to implement exponential backoff 49 | multiplier: f64, 50 | /// The maximum amount of jitter to add to the delay 51 | max-jitter-factor: option 52 | } 53 | ``` 54 | 55 | In python each field is represented by an _integer_. 56 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { MultiPlatformCommand } from "@/components/multi-platform-command" 2 | 3 | ## Setup development environment for Python 4 | 5 | Golem's Python toolchain is using [uv](https://docs.astral.sh/uv/) as the underlying build tool. 6 | Install it with the following command: 7 | 8 | 22 | -------------------------------------------------------------------------------- /src/pages/python-language-guide/updating.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Updating workers to newer versions of Python components 5 | 6 | As described in the general [Workers](/concepts/workers) page, each worker runs on a specific version of the component it is based on, but it is possible to **update** a worker to a different version of the same component. 7 | 8 | ## Automatic update 9 | 10 | The **automatic update** mode has no Python-specific details and works as it is described in the general [Workers](/concepts/workers) page. 11 | 12 | ## Manual snapshot-based update 13 | 14 | Sometimes the change between two component versions is so large that the only solution to migrate worker's state to a new version is to manually implement this state transfer. 15 | 16 | This is done by implementing a `save-snapshot` function in the old component and a `load-snapshot` function in the new component. The snapshot is an array of bytes and it is the responsibility of the user to ensure that the snapshot is compatible between the two versions. 17 | 18 | These functions are defined in the `golem:api` WIT package and must be explicitly exported from the component's `world`. 19 | -------------------------------------------------------------------------------- /src/pages/rest-api.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Card, Cards } from "nextra/components" 3 | import { GolemIcon } from "src/components/golem-logo" 4 | 5 | # REST API 6 | 7 | The REST APIs are organized in two sections: 8 | 9 | 10 | } /> 11 | } /> 12 | 13 | -------------------------------------------------------------------------------- /src/pages/rest-api/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "cloud-rest-api": { 3 | "title": "Cloud" 4 | }, 5 | "oss-rest-api": { 6 | "title": "Open Source" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api.mdx: -------------------------------------------------------------------------------- 1 | import { Card, Cards } from "nextra/components" 2 | 3 | # Golem Cloud REST API 4 | 5 | The following pages are the reference of the Golem Cloud REST APIs: 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/account.mdx: -------------------------------------------------------------------------------- 1 | # Account API 2 | The account API allows users to query and manipulate their own account data. 3 | ## Get account 4 | Path|Method|Protected 5 | ---|---|--- 6 | `/v1/accounts/{account_id}`|GET|Yes 7 | 8 | Retrieve an account for a given Account ID 9 | 10 | 11 | 12 | 13 | 14 | **Example Response JSON** 15 | 16 | ```json copy 17 | { 18 | "id": "string", 19 | "name": "string", 20 | "email": "string", 21 | "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d" 22 | } 23 | ``` 24 | 25 | ## Update account 26 | Path|Method|Protected 27 | ---|---|--- 28 | `/v1/accounts/{account_id}`|PUT|Yes 29 | 30 | Allows the user to change the account details such as name and email. 31 | 32 | Changing the planId is not allowed and the request will be rejected. 33 | The response is the updated account data. 34 | 35 | 36 | 37 | **Example Request JSON** 38 | ```json copy 39 | { 40 | "name": "string", 41 | "email": "string" 42 | } 43 | ``` 44 | 45 | **Example Response JSON** 46 | 47 | ```json copy 48 | { 49 | "id": "string", 50 | "name": "string", 51 | "email": "string", 52 | "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d" 53 | } 54 | ``` 55 | 56 | ## Delete account 57 | Path|Method|Protected 58 | ---|---|--- 59 | `/v1/accounts/{account_id}`|DELETE|Yes 60 | 61 | Delete an account. 62 | 63 | 64 | 65 | 66 | 67 | **Example Response JSON** 68 | 69 | ```json copy 70 | {} 71 | ``` 72 | 73 | ## Get account's plan 74 | Path|Method|Protected 75 | ---|---|--- 76 | `/v1/accounts/{account_id}/plan`|GET|Yes 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | **Example Response JSON** 85 | 86 | ```json copy 87 | { 88 | "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d", 89 | "planData": { 90 | "projectLimit": 0, 91 | "componentLimit": 0, 92 | "workerLimit": 0, 93 | "storageLimit": 0, 94 | "monthlyGasLimit": 0, 95 | "monthlyUploadLimit": 0 96 | } 97 | } 98 | ``` 99 | 100 | ## Create account 101 | Path|Method|Protected 102 | ---|---|--- 103 | `/v1/accounts`|POST|Yes 104 | 105 | Create a new account. The response is the created account data. 106 | 107 | 108 | 109 | **Example Request JSON** 110 | ```json copy 111 | { 112 | "name": "string", 113 | "email": "string" 114 | } 115 | ``` 116 | 117 | **Example Response JSON** 118 | 119 | ```json copy 120 | { 121 | "id": "string", 122 | "name": "string", 123 | "email": "string", 124 | "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d" 125 | } 126 | ``` 127 | ## Account API Errors 128 | Status Code|Description|Body 129 | ---|---|--- 130 | 400|Invalid request, returning with a list of issues detected in the request|`{"errors":["string"]}` 131 | 401|Unauthorized request|`{"error":"string"}` 132 | 404|Account not found|`{"error":"string"}` 133 | 500|Internal server error|`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/api-certificate.mdx: -------------------------------------------------------------------------------- 1 | # Api Certificate API 2 | 3 | ## Gets one or all certificates for a given project 4 | 5 | | Path | Method | Protected | 6 | | ---------------------- | ------ | --------- | 7 | | `/v1/api/certificates` | GET | Yes | 8 | 9 | If `certificate-id` is not set, it returns all certificates associated with the project. 10 | If `certificate-id` is set, it returns a single certificate if it exists. 11 | 12 | **Query Parameters** 13 | 14 | | Name | Type | Required | Description | 15 | | -------------- | ------ | -------- | ----------- | 16 | | project-id | string | Yes | - | 17 | | certificate-id | string | No | - | 18 | 19 | **Example Response JSON** 20 | 21 | ```json copy 22 | [ 23 | { 24 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 25 | "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", 26 | "domainName": "string", 27 | "createdAt": "2019-08-24T14:15:22Z" 28 | } 29 | ] 30 | ``` 31 | 32 | ## Creates a new certificate 33 | 34 | | Path | Method | Protected | 35 | | ---------------------- | ------ | --------- | 36 | | `/v1/api/certificates` | POST | Yes | 37 | 38 | A certificate is associated with a given Golem project and domain, and consists of 39 | a key pair. 40 | 41 | The created certificate will be associated with a certificate ID returned by this endpoint. 42 | 43 | **Example Request JSON** 44 | 45 | ```json copy 46 | { 47 | "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", 48 | "domainName": "string", 49 | "certificateBody": "string", 50 | "certificatePrivateKey": "string" 51 | } 52 | ``` 53 | 54 | **Example Response JSON** 55 | 56 | ```json copy 57 | { 58 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 59 | "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", 60 | "domainName": "string", 61 | "createdAt": "2019-08-24T14:15:22Z" 62 | } 63 | ``` 64 | 65 | ## Deletes a certificate 66 | 67 | | Path | Method | Protected | 68 | | ---------------------- | ------ | --------- | 69 | | `/v1/api/certificates` | DELETE | Yes | 70 | 71 | Deletes the certificate associated with the given certificate ID and project ID. 72 | 73 | **Query Parameters** 74 | 75 | | Name | Type | Required | Description | 76 | | -------------- | ------ | -------- | ----------- | 77 | | project-id | string | Yes | - | 78 | | certificate-id | string | Yes | - | 79 | 80 | **Example Response JSON** 81 | 82 | ```json copy 83 | "string" 84 | ``` 85 | 86 | ## Api Certificate API Errors 87 | 88 | | Status Code | Description | Body | 89 | | ----------- | ----------- | ----------------------------------------- | 90 | | 400 | | `{"type":"Messages","errors":["string"]}` | 91 | | 401 | | `{"error":"string"}` | 92 | | 403 | | `{"error":"string"}` | 93 | | 404 | | `{"message":"string"}` | 94 | | 409 | | `"string"` | 95 | | 500 | | `{"error":"string"}` | 96 | -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/api-domain.mdx: -------------------------------------------------------------------------------- 1 | # Api Domain API 2 | 3 | ## Get all API domains 4 | 5 | | Path | Method | Protected | 6 | | ----------------- | ------ | --------- | 7 | | `/v1/api/domains` | GET | Yes | 8 | 9 | Returns a list of API domains for the given project. 10 | 11 | **Query Parameters** 12 | 13 | | Name | Type | Required | Description | 14 | | ---------- | ------ | -------- | ----------- | 15 | | project-id | string | Yes | - | 16 | 17 | **Example Response JSON** 18 | 19 | ```json copy 20 | [ 21 | { 22 | "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", 23 | "domainName": "string", 24 | "nameServers": ["string"], 25 | "createdAt": "2019-08-24T14:15:22Z" 26 | } 27 | ] 28 | ``` 29 | 30 | ## Create or update an API domain 31 | 32 | | Path | Method | Protected | 33 | | ----------------- | ------ | --------- | 34 | | `/v1/api/domains` | PUT | Yes | 35 | 36 | **Example Request JSON** 37 | 38 | ```json copy 39 | { 40 | "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", 41 | "domainName": "string" 42 | } 43 | ``` 44 | 45 | **Example Response JSON** 46 | 47 | ```json copy 48 | { 49 | "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", 50 | "domainName": "string", 51 | "nameServers": ["string"], 52 | "createdAt": "2019-08-24T14:15:22Z" 53 | } 54 | ``` 55 | 56 | ## Delete an API domain 57 | 58 | | Path | Method | Protected | 59 | | ----------------- | ------ | --------- | 60 | | `/v1/api/domains` | DELETE | Yes | 61 | 62 | **Query Parameters** 63 | 64 | | Name | Type | Required | Description | 65 | | ---------- | ------ | -------- | ----------- | 66 | | project-id | string | Yes | - | 67 | | domain | string | Yes | - | 68 | 69 | **Example Response JSON** 70 | 71 | ```json copy 72 | "string" 73 | ``` 74 | 75 | ## Api Domain API Errors 76 | 77 | | Status Code | Description | Body | 78 | | ----------- | ----------- | ----------------------------------------- | 79 | | 400 | | `{"type":"Messages","errors":["string"]}` | 80 | | 401 | | `{"error":"string"}` | 81 | | 403 | | `{"error":"string"}` | 82 | | 404 | | `{"message":"string"}` | 83 | | 409 | | `"string"` | 84 | | 500 | | `{"error":"string"}` | 85 | -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/api-security.mdx: -------------------------------------------------------------------------------- 1 | # Api Security API 2 | 3 | ## Get a security scheme 4 | 5 | | Path | Method | Protected | 6 | | ------------------------------------------------------------ | ------ | --------- | 7 | | `/v1/api/security/{project_id}/{security_scheme_identifier}` | GET | Yes | 8 | 9 | Get a security scheme by name 10 | 11 | **Example Response JSON** 12 | 13 | ```json copy 14 | { 15 | "providerType": "Google", 16 | "schemeIdentifier": "string", 17 | "clientId": "string", 18 | "clientSecret": "string", 19 | "redirectUrl": "string", 20 | "scopes": ["string"] 21 | } 22 | ``` 23 | 24 | ## Create a security scheme 25 | 26 | | Path | Method | Protected | 27 | | ------------------------------- | ------ | --------- | 28 | | `/v1/api/security/{project_id}` | POST | Yes | 29 | 30 | **Example Request JSON** 31 | 32 | ```json copy 33 | { 34 | "providerType": "Google", 35 | "schemeIdentifier": "string", 36 | "clientId": "string", 37 | "clientSecret": "string", 38 | "redirectUrl": "string", 39 | "scopes": ["string"] 40 | } 41 | ``` 42 | 43 | **Example Response JSON** 44 | 45 | ```json copy 46 | { 47 | "providerType": "Google", 48 | "schemeIdentifier": "string", 49 | "clientId": "string", 50 | "clientSecret": "string", 51 | "redirectUrl": "string", 52 | "scopes": ["string"] 53 | } 54 | ``` 55 | 56 | ## Api Security API Errors 57 | 58 | | Status Code | Description | Body | 59 | | ----------- | ----------- | ----------------------------------------- | 60 | | 400 | | `{"type":"Messages","errors":["string"]}` | 61 | | 401 | | `{"error":"string"}` | 62 | | 403 | | `{"error":"string"}` | 63 | | 404 | | `{"message":"string"}` | 64 | | 409 | | `"string"` | 65 | | 500 | | `{"error":"string"}` | 66 | -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/limits.mdx: -------------------------------------------------------------------------------- 1 | # Limits API 2 | The limits API allows users to query their current resource limits. 3 | ## Get resource limits for a given account. 4 | Path|Method|Protected 5 | ---|---|--- 6 | `/v1/resource-limits`|GET|Yes 7 | 8 | 9 | 10 | **Query Parameters** 11 | 12 | Name|Type|Required|Description 13 | ---|---|---|--- 14 | account-id|string|Yes|The Account ID to check resource limits for. 15 | 16 | 17 | 18 | **Example Response JSON** 19 | 20 | ```json copy 21 | { 22 | "availableFuel": 0, 23 | "maxMemoryPerWorker": 0 24 | } 25 | ``` 26 | 27 | ## Update resource limits for a given account. 28 | Path|Method|Protected 29 | ---|---|--- 30 | `/v1/resource-limits`|POST|Yes 31 | 32 | 33 | 34 | 35 | 36 | **Example Request JSON** 37 | ```json copy 38 | { 39 | "updates": { 40 | "property1": 0, 41 | "property2": 0 42 | } 43 | } 44 | ``` 45 | 46 | **Example Response JSON** 47 | 48 | ```json copy 49 | {} 50 | ``` 51 | ## Limits API Errors 52 | Status Code|Description|Body 53 | ---|---|--- 54 | 400|Invalid request, returning with a list of issues detected in the request|`{"errors":["string"]}` 55 | 401|Unauthorized request|`{"error":"string"}` 56 | 403||`{"error":"string"}` 57 | 500|Internal server error|`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/project-grant.mdx: -------------------------------------------------------------------------------- 1 | # Project Grant API 2 | Projects can have grants providing access to other accounts than the project's owner. 3 | 4 | The project grant API allows listing, creating and deleting such grants. What the grants allow exactly are defined by policies, covered by the Project policy API. 5 | ## Get a project's grants 6 | Path|Method|Protected 7 | ---|---|--- 8 | `/v1/projects/{project_id}/grants`|GET|Yes 9 | 10 | Returns all projects grants associated with the given project. 11 | 12 | For each grant: 13 | - `id`` is the identifier of the grant itself 14 | - `granteeAccountId` the account that gets access for the project 15 | - `grantorProjectId` the project ID 16 | - `projectPolicyId` the associated policy - see the project policy API below 17 | 18 | 19 | 20 | 21 | 22 | **Example Response JSON** 23 | 24 | ```json copy 25 | [ 26 | { 27 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 28 | "data": { 29 | "granteeAccountId": "string", 30 | "grantorProjectId": "fe216e71-e471-414b-9530-d000f4582d33", 31 | "projectPolicyId": "46e8c3fb-5136-4f2a-a8be-e5188bef1348" 32 | } 33 | } 34 | ] 35 | ``` 36 | 37 | ## Create a project grant 38 | Path|Method|Protected 39 | ---|---|--- 40 | `/v1/projects/{project_id}/grants`|POST|Yes 41 | 42 | Creates a new project grant from the following information: 43 | - `granteeAccountId` the account that gets access for the project 44 | - `projectPolicyId` the associated policy - see the project policy API below 45 | 46 | The response describes the new project grant including its id that can be used to query specifically this grant in the future. 47 | 48 | 49 | 50 | **Example Request JSON** 51 | ```json copy 52 | { 53 | "granteeAccountId": "string", 54 | "projectPolicyId": "46e8c3fb-5136-4f2a-a8be-e5188bef1348", 55 | "projectActions": [ 56 | "ViewComponent" 57 | ], 58 | "projectPolicyName": "string" 59 | } 60 | ``` 61 | 62 | **Example Response JSON** 63 | 64 | ```json copy 65 | { 66 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 67 | "data": { 68 | "granteeAccountId": "string", 69 | "grantorProjectId": "fe216e71-e471-414b-9530-d000f4582d33", 70 | "projectPolicyId": "46e8c3fb-5136-4f2a-a8be-e5188bef1348" 71 | } 72 | } 73 | ``` 74 | 75 | ## Get a specific grant of a project 76 | Path|Method|Protected 77 | ---|---|--- 78 | `/v1/projects/{project_id}/grants/{grant_id}`|GET|Yes 79 | 80 | Returns a specific grant of a specific project. The returned object is the same as the elements of the grants endpoint's response described above. 81 | 82 | 83 | 84 | 85 | 86 | **Example Response JSON** 87 | 88 | ```json copy 89 | { 90 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 91 | "data": { 92 | "granteeAccountId": "string", 93 | "grantorProjectId": "fe216e71-e471-414b-9530-d000f4582d33", 94 | "projectPolicyId": "46e8c3fb-5136-4f2a-a8be-e5188bef1348" 95 | } 96 | } 97 | ``` 98 | 99 | ## Delete a project grant 100 | Path|Method|Protected 101 | ---|---|--- 102 | `/v1/projects/{project_id}/grants/{grant_id}`|DELETE|Yes 103 | 104 | Deletes an existing grant of a specific project. 105 | 106 | 107 | 108 | 109 | 110 | **Example Response JSON** 111 | 112 | ```json copy 113 | {} 114 | ``` 115 | ## Project Grant API Errors 116 | Status Code|Description|Body 117 | ---|---|--- 118 | 400|Invalid request, returning with a list of issues detected in the request|`{"errors":["string"]}` 119 | 401|Unauthorized|`{"error":"string"}` 120 | 403|Maximum number of projects exceeded|`{"error":"string"}` 121 | 404|Project not found|`{"error":"string"}` 122 | 500|Project already exists|`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/project-policy.mdx: -------------------------------------------------------------------------------- 1 | # Project Policy API 2 | Project policies describe a set of actions one account can perform when it was associated with a grant for a project. 3 | 4 | The following actions can be used in the projectActions fields of this API: 5 | - `ViewComponent` grants read access to a component 6 | - `CreateComponent` allows creating new components in a project 7 | - `UpdateComponent` allows uploading new versions for existing components in a project 8 | - `DeleteComponent` allows deleting components from a project 9 | - `ViewWorker` allows querying existing workers of a component belonging to the project 10 | - `CreateWorker` allows launching new workers of a component in the project 11 | - `UpdateWorker` allows manipulating existing workers of a component belonging to the project 12 | - `DeleteWorker` allows deleting workers of a component belonging to the project 13 | - `ViewProjectGrants` allows listing the existing grants of the project 14 | - `CreateProjectGrants` allows creating new grants for the project 15 | - `DeleteProjectGrants` allows deleting existing grants of the project 16 | ## Get a project policy 17 | Path|Method|Protected 18 | ---|---|--- 19 | `/v1/project-policies/{project_policy_id}`|GET|Yes 20 | 21 | Returns a given project policy by it's ID. Project policy identifiers are used in project grants. 22 | 23 | 24 | 25 | 26 | 27 | **Example Response JSON** 28 | 29 | ```json copy 30 | { 31 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 32 | "name": "string", 33 | "projectActions": { 34 | "actions": [ 35 | "ViewComponent" 36 | ] 37 | } 38 | } 39 | ``` 40 | 41 | ## Create a project policy 42 | Path|Method|Protected 43 | ---|---|--- 44 | `/v1/project-policies`|POST|Yes 45 | 46 | Creates a new project policy and returns the object describing it, including the newly created policy's id. 47 | 48 | 49 | 50 | **Example Request JSON** 51 | ```json copy 52 | { 53 | "name": "string", 54 | "projectActions": { 55 | "actions": [ 56 | "ViewComponent" 57 | ] 58 | } 59 | } 60 | ``` 61 | 62 | **Example Response JSON** 63 | 64 | ```json copy 65 | { 66 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 67 | "name": "string", 68 | "projectActions": { 69 | "actions": [ 70 | "ViewComponent" 71 | ] 72 | } 73 | } 74 | ``` 75 | ## Project Policy API Errors 76 | Status Code|Description|Body 77 | ---|---|--- 78 | 400|Invalid request, returning with a list of issues detected in the request|`{"errors":["string"]}` 79 | 401|Unauthorized request|`{"error":"string"}` 80 | 404|Account not found|`{"error":"string"}` 81 | 500|Internal server error|`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rest-api/cloud-rest-api/token.mdx: -------------------------------------------------------------------------------- 1 | # Token API 2 | The token API allows creating custom access tokens for the Golem Cloud REST API to be used by tools and services. 3 | ## Get all tokens 4 | Path|Method|Protected 5 | ---|---|--- 6 | `/v1/accounts/{account_id}/tokens`|GET|Yes 7 | 8 | Gets all created tokens of an account. 9 | The format of each element is the same as the data object in the oauth2 endpoint's response. 10 | 11 | 12 | 13 | 14 | 15 | **Example Response JSON** 16 | 17 | ```json copy 18 | [ 19 | { 20 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 21 | "accountId": "string", 22 | "createdAt": "2019-08-24T14:15:22Z", 23 | "expiresAt": "2019-08-24T14:15:22Z" 24 | } 25 | ] 26 | ``` 27 | 28 | ## Create new token 29 | Path|Method|Protected 30 | ---|---|--- 31 | `/v1/accounts/{account_id}/tokens`|POST|Yes 32 | 33 | Creates a new token with a given expiration date. 34 | The response not only contains the token data but also the secret which can be passed as a bearer token to the Authorization header to the Golem Cloud REST API. 35 | 36 | 37 | 38 | 39 | **Example Request JSON** 40 | ```json copy 41 | { 42 | "expiresAt": "2019-08-24T14:15:22Z" 43 | } 44 | ``` 45 | 46 | **Example Response JSON** 47 | 48 | ```json copy 49 | { 50 | "data": { 51 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 52 | "accountId": "string", 53 | "createdAt": "2019-08-24T14:15:22Z", 54 | "expiresAt": "2019-08-24T14:15:22Z" 55 | }, 56 | "secret": { 57 | "value": "a860a344-d7b2-406e-828e-8d442f23f344" 58 | } 59 | } 60 | ``` 61 | 62 | ## Get a specific token 63 | Path|Method|Protected 64 | ---|---|--- 65 | `/v1/accounts/{account_id}/tokens/{token_id}`|GET|Yes 66 | 67 | Gets information about a token given by it's identifier. 68 | The JSON is the same as the data object in the oauth2 endpoint's response. 69 | 70 | 71 | 72 | 73 | 74 | **Example Response JSON** 75 | 76 | ```json copy 77 | { 78 | "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 79 | "accountId": "string", 80 | "createdAt": "2019-08-24T14:15:22Z", 81 | "expiresAt": "2019-08-24T14:15:22Z" 82 | } 83 | ``` 84 | 85 | ## Delete a token 86 | Path|Method|Protected 87 | ---|---|--- 88 | `/v1/accounts/{account_id}/tokens/{token_id}`|DELETE|Yes 89 | 90 | Deletes a previously created token given by it's identifier. 91 | 92 | 93 | 94 | 95 | 96 | **Example Response JSON** 97 | 98 | ```json copy 99 | {} 100 | ``` 101 | ## Token API Errors 102 | Status Code|Description|Body 103 | ---|---|--- 104 | 400|Invalid request, returning with a list of issues detected in the request|`{"errors":["string"]}` 105 | 401|Unauthorized request|`{"error":"string"}` 106 | 404|Account not found|`{"error":"string"}` 107 | 500|Internal server error|`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rest-api/oss-rest-api.mdx: -------------------------------------------------------------------------------- 1 | import { Cards, Card } from "nextra/components" 2 | 3 | # Golem OSS REST API 4 | 5 | The following pages are the reference of the open-source Golem REST APIs: 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /src/pages/rest-api/oss-rest-api/api-deployment.mdx: -------------------------------------------------------------------------------- 1 | # Api Deployment API 2 | 3 | ## Creates or updates a deployment 4 | Path|Method|Protected 5 | ---|---|--- 6 | `/v1/api/deployments/deploy`|POST|No 7 | 8 | Deploys a set of API definitions to a site (specific host and subdomain). 9 | 10 | 11 | 12 | **Example Request JSON** 13 | ```json copy 14 | { 15 | "apiDefinitions": [ 16 | { 17 | "id": "string", 18 | "version": "string" 19 | } 20 | ], 21 | "site": { 22 | "host": "string", 23 | "subdomain": "string" 24 | } 25 | } 26 | ``` 27 | 28 | **Example Response JSON** 29 | 30 | ```json copy 31 | { 32 | "apiDefinitions": [ 33 | { 34 | "id": "string", 35 | "version": "string" 36 | } 37 | ], 38 | "site": { 39 | "host": "string", 40 | "subdomain": "string" 41 | }, 42 | "createdAt": "2019-08-24T14:15:22Z" 43 | } 44 | ``` 45 | 46 | ## Get one or more API deployments 47 | Path|Method|Protected 48 | ---|---|--- 49 | `/v1/api/deployments`|GET|No 50 | 51 | If `api-definition-id` is not set, it lists all API deployments. 52 | If `api-definition-id` is set, returns a single API deployment. 53 | 54 | **Query Parameters** 55 | 56 | Name|Type|Required|Description 57 | ---|---|---|--- 58 | api-definition-id|string|No|- 59 | 60 | 61 | 62 | **Example Response JSON** 63 | 64 | ```json copy 65 | [ 66 | { 67 | "apiDefinitions": [ 68 | { 69 | "id": "string", 70 | "version": "string" 71 | } 72 | ], 73 | "site": { 74 | "host": "string", 75 | "subdomain": "string" 76 | }, 77 | "createdAt": "2019-08-24T14:15:22Z" 78 | } 79 | ] 80 | ``` 81 | 82 | ## Get API deployment by site 83 | Path|Method|Protected 84 | ---|---|--- 85 | `/v1/api/deployments/{site}`|GET|No 86 | 87 | Gets an API deployment by the host name (optionally with a subdomain) it is deployed to. 88 | 89 | 90 | 91 | 92 | 93 | **Example Response JSON** 94 | 95 | ```json copy 96 | { 97 | "apiDefinitions": [ 98 | { 99 | "id": "string", 100 | "version": "string" 101 | } 102 | ], 103 | "site": { 104 | "host": "string", 105 | "subdomain": "string" 106 | }, 107 | "createdAt": "2019-08-24T14:15:22Z" 108 | } 109 | ``` 110 | 111 | ## Delete API deployment by site 112 | Path|Method|Protected 113 | ---|---|--- 114 | `/v1/api/deployments/{site}`|DELETE|No 115 | 116 | Deletes an API deployment by the host name (optionally with a subdomain) it is deployed to. 117 | 118 | 119 | 120 | 121 | 122 | **Example Response JSON** 123 | 124 | ```json copy 125 | "string" 126 | ``` 127 | ## Api Deployment API Errors 128 | Status Code|Description|Body 129 | ---|---|--- 130 | 400||`{"type":"Messages","errors":["string"]}` 131 | 401||`{"error":"string"}` 132 | 403||`{"error":"string"}` 133 | 404||`{"error":"string"}` 134 | 409||`"string"` 135 | 500||`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rest-api/oss-rest-api/api-security.mdx: -------------------------------------------------------------------------------- 1 | # Api Security API 2 | 3 | ## Get a security scheme 4 | Path|Method|Protected 5 | ---|---|--- 6 | `/v1/api/security/{security_scheme_identifier}`|GET|No 7 | 8 | Get a security scheme by name 9 | 10 | 11 | 12 | 13 | 14 | **Example Response JSON** 15 | 16 | ```json copy 17 | { 18 | "providerType": "Google", 19 | "schemeIdentifier": "string", 20 | "clientId": "string", 21 | "clientSecret": "string", 22 | "redirectUrl": "string", 23 | "scopes": [ 24 | "string" 25 | ] 26 | } 27 | ``` 28 | 29 | ## Create a security scheme 30 | Path|Method|Protected 31 | ---|---|--- 32 | `/v1/api/security`|POST|No 33 | 34 | 35 | 36 | 37 | 38 | **Example Request JSON** 39 | ```json copy 40 | { 41 | "providerType": "Google", 42 | "schemeIdentifier": "string", 43 | "clientId": "string", 44 | "clientSecret": "string", 45 | "redirectUrl": "string", 46 | "scopes": [ 47 | "string" 48 | ] 49 | } 50 | ``` 51 | 52 | **Example Response JSON** 53 | 54 | ```json copy 55 | { 56 | "providerType": "Google", 57 | "schemeIdentifier": "string", 58 | "clientId": "string", 59 | "clientSecret": "string", 60 | "redirectUrl": "string", 61 | "scopes": [ 62 | "string" 63 | ] 64 | } 65 | ``` 66 | ## Api Security API Errors 67 | Status Code|Description|Body 68 | ---|---|--- 69 | 400||`{"type":"Messages","errors":["string"]}` 70 | 401||`{"error":"string"}` 71 | 403||`{"error":"string"}` 72 | 404||`{"error":"string"}` 73 | 409||`"string"` 74 | 500||`{"error":"string"}` -------------------------------------------------------------------------------- /src/pages/rust-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps", 10 | "-- golem-sdk": { 11 | "type": "separator", 12 | "title": "Golem SDK" 13 | }, 14 | "http": "HTTP client", 15 | "durability": "Durability", 16 | "retries": "Retries", 17 | "transactions": "Transactions", 18 | "promises": "Promises", 19 | "updating": "Updating Workers", 20 | "wasi": "WASI" 21 | } 22 | -------------------------------------------------------------------------------- /src/pages/rust-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Building Golem Components in Rust 4 | 5 | Building Golem components having an [application manifest](/app-manifest) is straightforward, just use the `golem` command line interface: 6 | 7 | ```shell copy 8 | golem app build 9 | ``` 10 | 11 | If the project was created using `golem new` as recommended, the `golem app build` command will always work as expected. 12 | 13 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 14 | 15 | ```shell copy 16 | golem component add 17 | ``` 18 | 19 | ### IDE support 20 | 21 | Any IDE supporting Rust can be used, however for creating the result WASM file, the `cargo component build` command must be used instead of the usual `cargo build` command that the IDE might use under the hood. 22 | 23 | When using `rust-analyzer`, read the following section of the `cargo-component` documentation about how to configure it properly: https://github.com/bytecodealliance/cargo-component#using-rust-analyzer 24 | 25 | ### Under the hood 26 | Under the hood the `golem` tool performs a single call of the `cargo component build` command: 27 | 28 | ```shell 29 | $ cargo component build 30 | Generating bindings for example (src/bindings.rs) 31 | Compiling example v0.1.0 (/Users/golem/tmp/doc-temp/example) 32 | Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.33s 33 | Creating component target/wasm32-wasip1/debug/example.wasm 34 | ``` 35 | 36 | The `target/wasm32-wasip1/debug/example.wasm` file is a WebAssembly component ready to be uploaded to Golem. 37 | 38 | It is recommended to compile a **release build** of the component before deploying it to Golem as it is more optimized and smaller in size: 39 | 40 | ```shell 41 | $ cargo component build --release 42 | Generating bindings for example (src/bindings.rs) 43 | Compiling example v0.1.0 (/Users/golem/tmp/doc-temp/example) 44 | Finished `release` profile [optimized] target(s) in 0.33s 45 | Creating component target/wasm32-wasip1/release/example.wasm 46 | ``` 47 | 48 | 49 | Make sure the **Creating component ...** line is printed. Some previous versions of `cargo-component` failed silently in some cases, skipping the last part of packaging the built WebAssembly module into a **component**. 50 | 51 | It is possible to verify that the result `.wasm` is a valid WebAssembly component by using the `wasm-tools` CLI tool and running: 52 | 53 | ```shell 54 | $ wasm-tools print target/wasm32-wasip1/release/example.wasm --skeleton 55 | ``` 56 | 57 | The top-level node must be `component` and not `module`. 58 | 59 | 60 | -------------------------------------------------------------------------------- /src/pages/rust-language-guide/http.mdx: -------------------------------------------------------------------------------- 1 | # HTTP requests in Rust 2 | 3 | Golem implements the [WASI HTTP](https://github.com/WebAssembly/wasi-http) interfaces so any library built on this specification can be used from Golem components to communicate with external services. 4 | 5 | Currently there is only one such Rust library available, a fork of the popular `reqwest` library provided by the Golem team: https://github.com/golemcloud/reqwest/tree/update-april-2025 6 | 7 | ### Adding as a dependency 8 | 9 | To use it, add the following dependency to your component's `Cargo.toml`: 10 | 11 | ```toml 12 | [dependencies] 13 | reqwest = { git = "https://github.com/golemcloud/reqwest", branch = "update-april-2025", features = ["json"] } 14 | ``` 15 | 16 | Optionally add `serde` and `serde_json` to take advantage of `reqwest`'s JSON support: 17 | 18 | ```toml 19 | serde = { version = "1.0.203", features = ["derive"] } 20 | serde_json = "1.0.117" 21 | ``` 22 | 23 | ### Making a request 24 | 25 | The fork provides the same API as the official `reqwest` library's blocking API, documented [here](https://docs.rs/reqwest/latest/reqwest/blocking/index.html). 26 | 27 | In the following example we make a POST request sending a JSON payload and parsing the response as JSON using derived codecs by `serde`. 28 | 29 | First let's define the request and response body types: 30 | 31 | ```rust 32 | use serde::{Deserialize, Serialize}; 33 | 34 | #[derive(Clone, Debug, Serialize, Deserialize)] 35 | struct ExampleRequest { 36 | name: String, 37 | amount: u32, 38 | comments: Vec, 39 | } 40 | 41 | #[derive(Clone, Debug, Serialize, Deserialize)] 42 | struct ExampleResponse { 43 | percentage: f64, 44 | message: Option, 45 | } 46 | ``` 47 | 48 | Then in the worker's implementation we can use `reqwest` in the following way (proper error handling omitted for brevity): 49 | 50 | ```rust 51 | use reqwest::*; 52 | 53 | // ... 54 | 55 | let client = Client::builder().build().expect("Failed to create client"); 56 | 57 | let request_body = ExampleRequest { 58 | name: "Something".to_string(), 59 | amount: 42, 60 | comments: vec!["Hello".to_string(), "World".to_string()], 61 | }; 62 | 63 | let response: Response = client 64 | .post(&format!("http://example.com:8080/post-example")) 65 | .json(&request_body) 66 | .header("X-Test", "Golem") 67 | .basic_auth("some", Some("body")) 68 | .send() 69 | .expect("Request failed"); 70 | 71 | let status = response.status(); 72 | let body = response 73 | .json::() 74 | .expect("Invalid response"); 75 | 76 | println!("Received {:?} {:?}", status, body); 77 | ``` 78 | -------------------------------------------------------------------------------- /src/pages/rust-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the Rust development environment](/rust-language-guide/setup) and learning the basic steps [writing a Golem component](/rust-language-guide/defining-components) and [building them](/rust-language-guide/building-components), please consider learning about the following topics: 6 | 7 | 8 | ### Making HTTP requests from a Golem component 9 | Learn how to [send HTTP requests from a Golem component written in Rust](/rust-language-guide/http). 10 | 11 | ### Control durability guarantees 12 | 13 | Check how the Rust Golem SDK can [control various durability settings](/rust-language-guide/durability) of Golem. 14 | 15 | ### Automatic retries 16 | 17 | Learn about Golem's retry mechanism and [how it can be customized](/rust-language-guide/retries). 18 | 19 | ### Transactions 20 | 21 | Use the higher level [transactions library](/rust-language-guide/transactions) to implement the _Saga pattern_. 22 | 23 | ### Promises 24 | 25 | Create and use [promises](/rust-language-guide/promises) to await external events from within a running worker. 26 | 27 | ### Using WASI interfaces 28 | 29 | See what low-level [WASI interfaces](/rust-language-guide/wasi) are available and how they can be used from Rust. 30 | 31 | ### Call other workers from a worker 32 | 33 | [Worker to Worker communication](/common-language-guide/rpc) 34 | 35 | ### Set up the worker's filesystem 36 | 37 | [Worker filesystem](/common-language-guide/worker-filesystem) 38 | 39 | ### Share WIT packages between components 40 | 41 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 42 | 43 | ### Use LLMs 44 | 45 | [LLMs](/common-language-guide/llm) 46 | 47 | ### Use fork to achieve parallelism 48 | 49 | [Forking Workers](/common-language-guide/forking) 50 | 51 | 52 | -------------------------------------------------------------------------------- /src/pages/rust-language-guide/retries.mdx: -------------------------------------------------------------------------------- 1 | # Control the retry policy from Rust 2 | 3 | ### Using Golem's retry mechanism 4 | 5 | Golem applies a retry mechanism to all workers. In case of a failure, Golem will automatically recover the worker to the point before the failure and retry the operation. An exponential backoff and an upper limit on the number of retries are applied. 6 | 7 | If the maximum number of retries is reached, the worker will be marked as failed and no further invocations will be possible on it. 8 | 9 | This mechanism is automatic and applied to all kind of failures. To rely on it, just let the Rust code panic. 10 | 11 | ### Customizing the retry policy 12 | 13 | The retry policy which controls the maximum number of retries and the exponential backoff is a global configuration of the Golem servers, but it can be customized for each worker. 14 | 15 | For Rust we need to use the `golem-rust` crate to do so. 16 | First add it to the dependencies in your `Cargo.toml`: 17 | 18 | ```toml 19 | [dependencies] 20 | golem-rust = { version = "1.3.0" } 21 | ``` 22 | 23 | Then use the `use_retry_policy` or `with_retry_policy` functions to temporarily change the retry policy, either until the returned guard is dropped (the `use_` variant) or for the provided closure (the `with_` variant). 24 | 25 | ```rust 26 | let _guard = use_retry_policy(RetryPolicy { 27 | max_attempts: 10, 28 | min_delay: Duration::from_secs(1), 29 | max_delay: Duration::from_secs(1), 30 | multiplier: 1.0, 31 | max_jitter_factory: None 32 | }); 33 | // ... 34 | 35 | // or 36 | 37 | with_retry_policy(RetryPolicy { 38 | max_attempts: 10, 39 | min_delay: Duration::from_secs(1), 40 | max_delay: Duration::from_secs(1), 41 | multiplier: 1.0, 42 | max_jitter_factory: None 43 | }, || { 44 | // ... 45 | }); 46 | ``` 47 | 48 | The `RetryPolicy` type itself is originated from Golem's WIT definition in the following way: 49 | 50 | ```wit 51 | /// Configures how the executor retries failures 52 | record retry-policy { 53 | /// The maximum number of retries before the worker becomes permanently failed 54 | max-attempts: u32, 55 | /// The minimum delay between retries (applied to the first retry) 56 | min-delay: duration, 57 | /// The maximum delay between retries 58 | max-delay: duration, 59 | /// Multiplier applied to the delay on each retry to implement exponential backoff 60 | multiplier: f64 61 | } 62 | ``` 63 | -------------------------------------------------------------------------------- /src/pages/rust-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Setup Rust 4 | 5 | Creating **Golem components** in **Rust** requires installing the latest stable compiler, enabling the WASM target and installing the supported version of `cargo-component`. 6 | 7 | ### Installing Rust 8 | 9 | Use the [official guide](https://www.rust-lang.org/learn/get-started) to install the latest **stable** version of the Rust compiler. 10 | 11 | 12 | For MacOS the recommended way is using `rustup` by running the following installation script: 13 | 14 | ```shell 15 | $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 16 | ``` 17 | 18 | 19 | 20 | ### Enabling WebAssembly targets 21 | 22 | With `rust` and `rustup` installed, the next step is to **enable the WebAssembly** support by running: 23 | 24 | ```shell 25 | $ rustup target add wasm32-wasip1 26 | ``` 27 | 28 | To verify if this step was successful, run: 29 | 30 | ```shell 31 | $ rustup target list --installed | grep wasm32-wasip1 32 | wasm32-wasip1 33 | ``` 34 | 35 | ### Installing `cargo-component` 36 | 37 | The last step is installing the `cargo-component` extension for Rust's `cargo` build tool. This will enable a set of subcommands for `cargo` which allows compiling Rust projects into **WebAssembly components**, which are ready to be uploaded to **Golem**. 38 | 39 | 40 | Golem requires a **specific version** of `cargo-component`. Please make sure the correct version 41 | is installed with the commands described below. 42 | 43 | 44 | Install the version `0.20.0` of `cargo-component` with `cargo` itself: 45 | 46 | ```shell 47 | $ cargo install --force cargo-component@0.20.0 48 | ``` 49 | 50 | 51 | There is a bug in one of `cargo-component`'s dependencies (`wit-component 0.220.0`), fixed by a patch release (`wit-component 0.220.1`). Make sure to NOT use `--locked` otherwise you get the wrong version of this dependency installed, which can lead to runtime errors regarding _misaligned pointer dereference_. 52 | 53 | 54 | Verify that the correct version is installed: 55 | 56 | ```shell 57 | $ cargo component --version 58 | cargo-component-component 0.20.0 (2e497ee 2025-01-07) 59 | ``` 60 | 61 | Please refer [to the cargo-component website](http://github.com/bytecodealliance/cargo-component) for more information. 62 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "-- getting-started": { 3 | "type": "separator", 4 | "title": "Getting Started" 5 | }, 6 | "setup": "Setup", 7 | "defining-components": "Defining Components", 8 | "building-components": "Building Components", 9 | "next-steps": "Next Steps", 10 | "-- golem-sdk": { 11 | "type": "separator", 12 | "title": "Golem SDK" 13 | }, 14 | "golem-ts-sdk": "Setting up the Golem TypeScript SDK", 15 | "http": "HTTP client", 16 | "durability": "Durability", 17 | "retries": "Retries", 18 | "transactions": "Transactions", 19 | "promises": "Promises", 20 | "updating": "Updating Workers", 21 | "wasi": "WASI" 22 | } 23 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/building-components.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Building Golem Components in TypeScript 5 | Building Golem components having an [application manifest](/app-manifest) is straightforward. 6 | 7 | First (or after changing the `package.json` file) we have to install the `npm` dependencies with a custom command defined in the Golem TypeScript template: 8 | 9 | ```shell copy 10 | golem app ts-npm-install 11 | ``` 12 | 13 | Then just use the `golem` command line interface to run the build: 14 | 15 | ```shell copy 16 | golem app build 17 | ``` 18 | 19 | If the project was created using `golem app new` as recommended, the `golem app build` command will always work as expected. 20 | 21 | The result of the `golem app build` command is a WebAssembly component file ready to be uploaded to Golem. It does not have to be specified explicitly, as the `golem` tool will automatically find the correct file when doing for example: 22 | 23 | ```shell copy 24 | golem component add 25 | ``` 26 | 27 | ## Under the hood 28 | Building Golem components written in TypeScript requires a series of steps. 29 | 30 | If the project was created with `golem new`, it already has a `package.json` that incorporates all the necessary steps as _npm scripts_ to build the component, so it is enough to run: 31 | 32 | ```shell 33 | $ npm run componentize 34 | ``` 35 | 36 | In details, building the component requires the following steps: 37 | 38 | 39 | ### Generate the TypeScript bindings 40 | 41 | For generating the binding we use the Golem fork of `jco` and `componentize-js`. When using the `golem` examples, these dependencies are included in `package.json`, and an _npm script_ called `stub` is also defined: 42 | 43 | ```shell 44 | $ npm run stub 45 | ``` 46 | 47 | The generated binding will placed in the `src/generated` directory. 48 | 49 | The above run command will execute the following commands: 50 | 51 | ```shell 52 | $ jco stubgen wit -o src/generated 53 | ``` 54 | 55 | And requires the following dev dependencies: 56 | 57 | ```json 58 | { 59 | "devDependencies": { 60 | "@golemcloud/componentize-js": "0.10.2-golem.1", 61 | "@golemcloud/jco": "1.4.0-golem.1" 62 | } 63 | } 64 | ``` 65 | 66 | ### Compile the TypeScript code to JavaScript 67 | 68 | The examples use `rollup` through an _npm script_ to compile _TypeScript_ to _JavaScript_: 69 | 70 | ```shell 71 | $ npm run build 72 | ``` 73 | 74 | This will compile all the _TypeScript_ sources into a **single** _JavaScript_ file at `out/main.js`. 75 | 76 | ### Componentizing the JavaScript code 77 | 78 | The final step is **componentizing**, which involves: 79 | 80 | - embedding our _JavaScript_ code into the _StarlingMonkey JS engine_ 81 | - running _Wizer pre-initialization_, which pre-loads and parses our Javascript source in the JS engine 82 | - creating the _wasm output_ file for our component with it's interface exposed as a _WebAssembly component_ usable by _Golem_. 83 | 84 | The example projects includes an _npm script_ called `componentize`, which also includes the previous `stub` and `build` steps. 85 | 86 | ```shell 87 | $ npm run componentize 88 | ``` 89 | 90 | The output wasm file with be created with the built component name, eg.: `out/example.wasm`. 91 | 92 | The above _npm script_ will execute the following commands: 93 | 94 | ``` 95 | $ npm run stub && npm run build && jco componentize -w wit -o out/example.wasm out/main.js 96 | ``` 97 | 98 | 99 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/golem-ts-sdk.mdx: -------------------------------------------------------------------------------- 1 | import { Callout, Steps, Tabs } from "nextra/components" 2 | import { AllWitDeps } from "@/components/all-wit-deps" 3 | import { MultiPlatformCommand } from "@/components/multi-platform-command" 4 | 5 | # Setting up the Golem TypeScript SDK 6 | 7 | 8 | If the project was created with `golem new`, it already has the Golem TypeScript SDK set up 9 | and these steps can be ignored. 10 | 11 | 12 | To add the [Golem JavaScript SDK](https://github.com/golemcloud/golem-ts) to a project, just install it using npm; 13 | 21 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/http.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # HTTP requests in TypeScript 4 | 5 | Golem implements the [WASI HTTP](https://github.com/WebAssembly/wasi-http) interfaces so any library built on this specification can be used from Golem components to communicate with external services. 6 | HTTP request can also be made with the JavaScript standard builtin `fetch` function. 7 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import { Steps } from "nextra/components" 2 | 3 | # Next steps 4 | 5 | After [setting up the TypeScript development environment](/ts-language-guide/setup) and learning the basic steps [writing a Golem component](/ts-language-guide/defining-components) and [building them](/ts-language-guide/building-components), please consider learning about the following topics: 6 | 7 | 8 | ### Making HTTP requests from a Golem component 9 | Learn how to [send HTTP requests from a Golem component written in TypeScript](/ts-language-guide/http). 10 | 11 | ### Control durability guarantees 12 | 13 | Check how the TypeScript Golem SDK can [control various durability settings](/ts-language-guide/durability) of Golem. 14 | 15 | ### Automatic retries 16 | 17 | Learn about Golem's retry mechanism and [how it can be customized](/ts-language-guide/retries). 18 | 19 | ### Transactions 20 | 21 | Use the higher level [transactions library](/ts-language-guide/transactions) to implement the _Saga pattern_. 22 | 23 | ### Promises 24 | 25 | Create and use [promises](/ts-language-guide/promises) to await external events from within a running worker. 26 | 27 | ### Using WASI interfaces 28 | 29 | See what low-level [WASI interfaces](/ts-language-guide/wasi) are available and how they can be used from TypeScript. 30 | 31 | ### Call other workers from a worker 32 | 33 | [Worker to Worker communication](/common-language-guide/rpc) 34 | 35 | ### Set up the worker's filesystem 36 | 37 | [Worker filesystem](/common-language-guide/worker-filesystem) 38 | 39 | ### Share WIT packages between components 40 | 41 | [Shared WIT packages](/common-language-guide/shared-wit-packages) 42 | 43 | ### Use LLMs 44 | 45 | [LLMs](/common-language-guide/llm) 46 | 47 | ### Use fork to achieve parallelism 48 | 49 | [Forking Workers](/common-language-guide/forking) 50 | 51 | 52 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/promises.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | 3 | # Working with Golem Promises in TypeScript 4 | 5 | Golem **promises** provide a way for Golem workers to wait on an external condition. The worker creates the promise and somehow sends its identifier to the external system responsible for **completing** the promise. Then the worker can **await** the promise, being suspended until the external system completes the promise using Golem's REST API. 6 | 7 | It is also possible to complete a promise from within a Golem worker using the Golem SDK. 8 | 9 | When a promise is completed, an arbitrary byte array can be attached to it as a payload - this data is returned to the awaiting worker when is continues execution. 10 | 11 | In TypeScript the promise API has idiomatic TypeScript wrappers in the [Golem TypeScript SDK](/ts-language-guide/golem-ts-sdk). 12 | 13 | ### Creating a promise 14 | 15 | To create a promise simply call the `createPromise` function: 16 | 17 | ```typescript 18 | import { createPromise, PromiseId } from "@golemcloud/golem-ts" 19 | 20 | const promiseId: PromiseId = createPromise() 21 | ``` 22 | 23 | The returned value has the type `PromiseId`, and defined as the following (including the nested types): 24 | 25 | ```typescript 26 | export type OplogIndex = bigint 27 | 28 | export interface Uuid { 29 | highBits: bigint 30 | lowBits: bigint 31 | } 32 | 33 | // Represents a Component 34 | export interface ComponentId { 35 | uuid: Uuid 36 | } 37 | 38 | // Represents a Worker 39 | export interface WorkerId { 40 | componentId: ComponentId 41 | workerName: string 42 | } 43 | 44 | // A promise ID is a value that can be passed to an external Golem API to complete that promise 45 | // from an arbitrary external source, while Golem workers can await for this completion. 46 | export interface PromiseId { 47 | workerId: WorkerId 48 | oplogIdx: OplogIndex 49 | } 50 | ``` 51 | 52 | ### Deleting a promise 53 | 54 | If a promise is no longer used, it has to be deleted with: 55 | 56 | ```typescript 57 | import { deletePromise, PromiseId } from "@golemcloud/golem-ts" 58 | 59 | deletePromise(promiseId) 60 | ``` 61 | 62 | ### Awaiting a promise 63 | 64 | To await a promise, use the `awaitPromise` functions, which returns the promise result as a byte array payload. 65 | Here's an example that awaits a promise, then decodes the payload from JSON format: 66 | 67 | ```typescript 68 | import { awaitPromise, PromiseId } from "@golemcloud/golem-ts" 69 | 70 | const byteArrayPayload: Uint8Array = awaitPromise(promiseId) 71 | const payload = JSON.parse(new TextDecoder().decode(byteArrayPayload)) 72 | ``` 73 | 74 | ### Completing a promise from within a worker 75 | 76 | To complete a promise from within a worker, use the `completePromise` function. 77 | The following example completes a promise with a value encoded as JSON: 78 | 79 | ```typescript 80 | import { completePromise, PromiseId } from "@golemcloud/golem-ts" 81 | 82 | const payload = { 83 | id: "value", 84 | meta: "data", 85 | } 86 | const byteArrayPayload: Uint8Array = new TextEncoder().encode(JSON.stringify(payload)) 87 | const success: boolean = completePromise(promiseId, byteArrayPayload) 88 | ``` 89 | 90 | ### Completing a promise from an external source 91 | 92 | To see how to use the **promise ID** to complete a promise through the external REST API, check [the REST API documentation](/rest-api). 93 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/retries.mdx: -------------------------------------------------------------------------------- 1 | # Control the retry policy from TypeScript 2 | 3 | ### Using Golem's retry mechanism 4 | 5 | Golem applies a retry mechanism to all workers. In case of a failure, Golem will automatically recover the worker to the point before the failure and retry the operation. An exponential backoff and an upper limit on the number of retries are applied. 6 | 7 | If the maximum number of retries is reached, the worker will be marked as failed and no further invocations will be possible on it. 8 | 9 | This mechanism is automatic and applied to all kind of failures. To rely on it, just throw an unhandled exception. 10 | 11 | ### Customizing the retry policy 12 | 13 | The retry policy which controls the maximum number of retries and the exponential backoff is a global configuration of the Golem servers, but it can be customized for each worker. 14 | 15 | The `golem-ts` library exports the `withRetryPolicy` function to temporarily change the retry policy: 16 | 17 | ```typescript 18 | import { withRetryPolicy } from "@golemcloud/golem-ts" 19 | 20 | // Durations are expected as nanoseconds 21 | const result: string = withRetryPolicy( 22 | { 23 | maxAttempts: 3, 24 | minDelay: BigInt(100 * 1000 * 1000), // 100 milliseconds 25 | maxDelay: BigInt(2 * 1000 * 1000 * 1000), // 2 seconds 26 | multiplier: 1.5, 27 | maxJitterFactor: null, 28 | }, 29 | () => { 30 | // this closure runs with the custom retry policy 31 | return "hello" 32 | } 33 | ) 34 | ``` 35 | 36 | The `RetryPolicy` interface required by `withRetryPolicy` is generated from Golem's WIT definition: 37 | 38 | ```wit 39 | /// Configures how the executor retries failures 40 | record retry-policy { 41 | /// The maximum number of retries before the worker becomes permanently failed 42 | max-attempts: u32, 43 | /// The minimum delay between retries (applied to the first retry) 44 | min-delay: duration, 45 | /// The maximum delay between retries 46 | max-delay: duration, 47 | /// Multiplier applied to the delay on each retry to implement exponential backoff 48 | multiplier: f64, 49 | /// The maximum amount of jitter to add to the delay 50 | max-jitter-factor: option 51 | } 52 | ``` 53 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/setup.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | ## Setup development environment for TypeScript 5 | 6 | Golem's TypeScript toolchain is using npm as the underlying build tool. 7 | Install **Node.js** and **npm** to your system by following the official [instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). 8 | -------------------------------------------------------------------------------- /src/pages/ts-language-guide/updating.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from "nextra/components" 2 | import { Steps } from "nextra/components" 3 | 4 | # Updating workers to newer versions of TypeScript components 5 | 6 | As described in the general [Workers](/concepts/workers) page, each worker runs on a specific version of the component it is based on, but it is possible to **update** a worker to a different version of the same component. 7 | 8 | ## Automatic update 9 | 10 | The **automatic update** mode has no TypeScript-specific details and works as it is described in the general [Workers](/concepts/workers) page. 11 | 12 | ## Manual snapshot-based update 13 | 14 | Sometimes the change between two component versions is so large that the only solution to migrate worker's state to a new version is to manually implement this state transfer. 15 | 16 | This is done by implementing a `save-snapshot` function in the old component and a `load-snapshot` function in the new component. The snapshot is an array of bytes and it is the responsibility of the user to ensure that the snapshot is compatible between the two versions. 17 | 18 | These functions are defined in the `golem:api` WIT package and must be explicitly exported from the component's `world`. 19 | -------------------------------------------------------------------------------- /src/styles/globals.css: -------------------------------------------------------------------------------- 1 | @tailwind base; 2 | @tailwind components; 3 | @tailwind utilities; 4 | 5 | /* Table of contents */ 6 | .nextra-toc > div.nextra-scrollbar > div:last-child { 7 | @apply bg-background-light shadow-none dark:bg-background-dark; 8 | } 9 | 10 | /* Theme switcher and collapse */ 11 | aside.nextra-sidebar-container > div:last-child { 12 | @apply bg-background-light shadow-none dark:bg-background-dark; 13 | } 14 | 15 | @layer base { 16 | * { 17 | /* Handle overly bold fonts in safari */ 18 | -webkit-font-smoothing: antialiased; 19 | min-width: 0; 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /tailwind.config.ts: -------------------------------------------------------------------------------- 1 | import type { Config } from "tailwindcss" 2 | 3 | const config: Config = { 4 | content: [ 5 | "./src/pages/**/*.{js,ts,jsx,tsx,mdx}", 6 | "./src/components/**/*.{js,ts,jsx,tsx,mdx}", 7 | "./src/app/**/*.{js,ts,jsx,tsx,mdx}", 8 | "./theme.config.tsx", 9 | ], 10 | theme: { 11 | extend: { 12 | fontFamily: { 13 | sans: ["var(--font-sans)"], 14 | }, 15 | backgroundImage: { 16 | "gradient-radial": "radial-gradient(var(--tw-gradient-stops))", 17 | "gradient-conic": "conic-gradient(from 180deg at 50% 50%, var(--tw-gradient-stops))", 18 | }, 19 | colors: { 20 | "background-dark": "#0a0a0a", 21 | "background-light": "#ffffff", 22 | }, 23 | }, 24 | }, 25 | plugins: [], 26 | darkMode: "class", 27 | } 28 | export default config 29 | -------------------------------------------------------------------------------- /theme.config.tsx: -------------------------------------------------------------------------------- 1 | import React from "react" 2 | import { DocsThemeConfig } from "nextra-theme-docs" 3 | import { Footer } from "@/components/footer" 4 | import { GolemLogo } from "@/components/golem-logo" 5 | import { useRouter } from "next/router" 6 | 7 | const config: DocsThemeConfig = { 8 | logo: , 9 | banner: { 10 | key: "docs-launch", 11 | text: ( 12 |
13 | Welcome to the new Golem Cloud Docs! 👋 14 |
15 | ), 16 | }, 17 | primaryHue: { 18 | dark: 213, 19 | light: 226, 20 | }, 21 | primarySaturation: { 22 | light: 90, 23 | dark: 93, 24 | }, 25 | sidebar: { 26 | toggleButton: true, 27 | defaultMenuCollapseLevel: 1, 28 | }, 29 | project: { 30 | link: "https://github.com/golemcloud/docs", 31 | }, 32 | chat: { 33 | link: "https://discord.gg/UjXeH8uG4x", 34 | }, 35 | docsRepositoryBase: "https://github.com/golemcloud/docs/blob/main", 36 | footer: { 37 | component: