Gray
Build your first Gray service.
Gray is a server language with native HTTP, cooperative I/O, typed application boundaries, and standalone deployment.
gray new hello-gray
cd hello-gray
gray devset $server = tcp_listen("127.0.0.1", 8080);
http_configure($server, 16384, 30000, 16777216);
while (true) {
set $request = http_poll($server, -1);
if ($request) {
if (http_route($request, "GET", "/")) {
http_respond(
$request,
200,
"text/plain",
"Hello from Gray"
);
} else {
http_respond($request, 404, "text/plain", "Not Found");
}
}
}200 · Hello from Gray
Adaptive mode
Five-minute service
Serve a typed controller directly.
This is the tested Gray web API starter. The listener, router, request continuation, and response path are runtime primitives.
import "./controllers/health.gy";
set HealthController $health = HealthController(
env_get("GRAY_SERVICE_NAME")
);
set $server = tcp_listen(
"0.0.0.0",
env_int("GRAY_PORT", 8080)
);
http_configure($server, 4096, 30000, 1048576);
http_handler(
$server,
"GET",
"/health",
"HealthController.handle",
[$health]
);
while (true) {
http_run($server, -1);
}Run it
GRAY_SERVICE_NAME=gray-web-api \
GRAY_PORT=8080 gray dev
curl http://127.0.0.1:8080/healthResponse
{"service":"gray-web-api","status":"ok"}
Adaptive mode compiles a candidate, waits for listener readiness, publishes it, and drains the previous worker.
Project anatomy
One strict manifest. No hidden discovery.
A gray.json identifies the package, entry, tests, local
dependencies, and timeout policy.
{
"name": "gray-web-api",
"version": "0.1.0",
"entry": "src/main.gy",
"tests": ["tests/health.test.gy"],
"test_timeout_ms": 5000
}
Dependency paths are explicit and package-confined. gray lock
records source inventories, hashes, constraints, and the complete local
dependency graph. Network registries are not part of the v0 contract.
Language
Dynamic where convenient. Typed where it matters.
Gray supports typeless values alongside checked parameters, returns, fields, collections, schemas, and nominal class references.
Functions and values
Use ordinary control flow with explicit typed boundaries.
function int total(int[] $values)
Classes and identity
Constructors, methods, private fields, references, and $this.
set Counter $copy = $counter;
Structured tasks
Spawn, await, and cancel while preserving source-aware failures.
set $result = await($task);
Binary-safe I/O
String is valid UTF-8. Bytes remains arbitrary binary.
set Bytes $body = http_body($request);
class Counter {
private int $value;
public constructor(int $initial) {
$this.value = $initial;
}
public int increment() {
$this.value = $this.value + 1;
return $this.value;
}
}
set Counter $counter = Counter(41);
echo $counter.increment();Data path
JSON and PostgreSQL are native application primitives.
Parameter binding, typed row decoding, pooled connections, explicit transactions, and readiness-driven query progress share the runtime.
set $rows = pg_query(
$database,
"SELECT id, email FROM users WHERE id = $1",
[$userId]
);
http_respond(
$request,
200,
"application/json; charset=utf-8",
json_encode($rows[0])
);The handler frame suspends while PostgreSQL becomes ready. The HTTP reactor continues serving other connections without consuming a general task worker.
Execution
One language. Three operating policies.
Output, types, security checks, and errors remain the same when the execution policy changes.
gray app.gy
Compile in memory and run immediately.
gray dev
Validate, replace, and drain a running server.
gray build app.gy -o app
Ship a standalone executable with native code and fallback.
Toolchain
The daily loop is already in the binary.
gray newCreate a strict project safely.gray devRun with validated Adaptive replacement.gray testExecute isolated manifest tests.gray fmtFormat source deterministically.gray lintCompile-check projects without execution.gray lspStart compiler-backed editor intelligence.gray doctorInspect project and environment health.gray docGenerate structured API documentation.gray traceCapture runtime tracing output.gray buildProduce a standalone Static executable.gray signSign an artifact and manifest.gray verifyVerify artifact identity and signature.Compiler-generated reference
Native API explorer.
The index below is generated from the current Gray compiler and runtime, then published with this site.
Loading compiler reference…
Select a declaration to inspect its current contract.
Current contract
Production-minded. Pre-1.0.
Gray already powers this site and has qualified language, HTTP, TLS, PostgreSQL, native lowering, tooling, and artifact paths. APIs can still change while the language is in active development.