@ exedev/ sdk
官方 Java 脚本/ Type 脚本 SDK exe.dev (英语) HTTPS API. (英语).
npm install @exedev/sdk
快开始
import exedev from "@exedev/sdk";
const exe = exedev({ token: process.env.EXE_TOKEN! });
const vm = await exe.new({ name: "my-vm", image: "ubuntu:24.04", tag: ["dev"] });
// new waits for SSH by default. No create-then-ssh retry loop is needed.
try {
console.log(vm.name, vm.httpsUrl);
const result = await vm.ssh("uname -a");
console.log(result.exitCode, result.stdout, result.stderr);
await vm.shareAdd("[email protected]", { message: "have a look" });
} finally {
await vm.rm();
}
客户端和VM API
exedev({ token, baseURL?, fetch? }) 创建客户端. baseURL 默认为
https://exe.dev· ; fetch 默认执行。 已命名的进口
联 合 国 exedev, (中文(简体) ), ExedevClient,以及 VM 也可查阅.
exe.new(options?)创建 VM 并返回 aVM对象.exe.ls(nameOrPattern?, options?)返回时VM[]。 。 。 .exe.vm(name)引用一个不提出请求的现有 VM .vm.refresh(options?)刷新其元数据并返回同一对象.vm.ssh(command, options?)运行一个贝壳命令 在VM.vm.cp({ name?, ...options })复制并返回一个新的VM对象.exe.rm(vms)删除一个请求中的 VM 或名称数组; 服务器 一次删除数个。 它决心{ deleted, failed, not_found, errors }而不是丢入 VM , 它不能删除 .- 生命周期和VM-扫描指令是VM上的方法:
vm.rm(), (中文(简体) ),vm.pause(), (中文(简体) ),vm.resume(), (中文(简体) ),vm.restart(), (中文(简体) ),vm.rename(newName), (中文(简体) ),vm.resize(options), (中文(简体) ),vm.stat(options), (中文(简体) ),vm.tag(tags), (中文(简体) ),vm.comment(text), (中文(简体) ),vm.shareShow(), (中文(简体) ),vm.sharePort(port),其他生成的 VM 命令. - 客户端仍保留账户命令 :
exe.whoami(), (中文(简体) ),exe.sshKeyList(), (中文(简体) ),exe.integrationsList(), (中文(简体) ),exe.billingPlan()等 (中文(简体) ).
没有平行的原始命令 API 或客户端级别 ssh 或者说 cp。 。 。 . vm.rm()
掷出 ExeAPIError 如果 VM 不删除,则 status 404 如果不是的话
已存在.
生成命令的选项保留 CLI 旗帜名称( 例如, ),
{ "no-email": true }; 每种方法都带有服务器的帮助文本.
除了每个 VM 命令 grantSupportRoot,以及 whoami拥有一个已知的JSON
反应:它的方法拒绝其他任何东西,并解决反应
类型。 电线类型(VMRecord, (中文(简体) ), NewResponse, (中文(简体) ), ShareShowResponse,(...)为
导出。 少数报告结果是问题而不是错误:
domainAdd 当 DNS 尚未指向 exe.dev 时 shelleyInstall 何时
舍利失踪; 窄与 "error" in result。其他账户命令
可能返回 JSON 或文本,并输入为 unknown。 。 。 .
vm.name 是当前名称. vm.httpsUrl, (中文(简体) ), vm.sshDest,以及 vm.tags 曝光
普通元数据. vm.info 是一个只读快照 status, (中文(简体) ), region, (中文(简体) ),
comment, (中文(简体) ), createdAt,以及 promptError (为什么) new是因为 prompt 未达到
舍利来时. 参考来源 exe.vm(name) 最初只知道
名称, 无标签; 调用 refresh() 去拿剩下的东西 副本来自 cp()
有标记和网络 URL 服务器报告它。 SDK自己的行动
更新快照:通过备战等待的 VM 是 running,以及
pause(), (中文(简体) ), resume(), (中文(简体) ), comment(),以及 tag() 记录他们改变了什么。 A 类
已经成功 rename() 更新同一对象,并使用新的 SSH 对象和
网络 URL 服务器报告 .
其他参考资料和其他地方所作的改动,需要 refresh()。 。 。 .
准备和取消
new, (中文(简体) ), cp, (中文(简体) ), restart,以及 resume 默认等待 SSH 。 过
{ waitUntil: "created" } 返回时不检查,包括当符号
没有 ssh 允许. vm.waitUntilReady({ waitUntil?, timeoutMs?, signal? })
明确等待以后。 默认准备时间为60秒 之后
创建或生命周期操作返回,包括探测请求和后退.
准备只运行无害的命令 true,重试瞬间连接
失败。 它从不重复用户命令或创建请求,而是
不等待应用程序服务器.
{ waitUntil: "setup" } 也等待 VM 的设置脚本(new是因为
"setup-script",由exeuntu的运行 exe-setup.service结束,投票
单位超过SSH,默认截止时间为10分钟. 如果剧本失败,则
VMReadyError是因为 cause 是一个 VMSetupError 与 exitCode (或 signal和
系统 result· ; details().output 拥有其日志的结尾。 只有exeuntu,
默认的图像, 以及在其上所建的图像 运行设置脚本: 在其它的, 例如
作为 ubuntu:24.04剧本没有运行,等待它是一个
VMSetupError 与 result "unsupported"。没有剧本,什么也没有
等待,一旦一个脚本运行了,以后的重启不会等待它.
const vm = await exe.new({ "setup-script": "#!/bin/sh\nsudo apt-get install -y jq", waitUntil: "setup" });
如果等待失败, VMReadyError.vm - 向您提供核查或清理的车辆;
它不会自动被删除。 包括一个没有 ssh
权限: 探测器被拒绝, 错误说要使用
waitUntil: "created"。所有行动接受 AbortSignal。 。 。 .
调用者取消保留 signal.reason,包括在溪流和
召回,而不是将其打入另一个错误中。 中止的创建可能
仍然创建了 VM; 使用明确的名称或 ls() 把它找回来.
运行命令
vm.ssh() 决定: { exitCode, stdout, stderr, stdoutBytes, stderrBytes, captured }。一个非零退出代码是结果,而不是例外;一个命令被杀死
通过信号N出口128+N,如在外壳. b. 字节数组保存二进制输出;
字符串被解码为UTF-8. 命令是 shell 脚本: 引用任何不可信
数值 quote。 。 。 .
import { quote } from "@exedev/sdk";
await vm.ssh(`cat ${quote(path)}`);
命令运行在非日志外壳中. 变量从 new是因为 env 设定为
它们(一旦VM的exe-init有更新,则使用;然后使用)
bash -lc) (中文(简体) ). 长而无声的命令是好的:服务器保持了响应的活性.
await vm.ssh("make", {
capture: false,
onStdout: (chunk) => { process.stdout.write(chunk); },
onStderr: (chunk) => { process.stderr.write(chunk); },
});
连续等待回调,每条流都有递增的UTF-8解码. 它们的跨流顺序大致相同. 从召回中丢弃取消 回答错误,并拒绝错误.
输出默认被捕获, 带有 8个米B综合限值 {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}然后呢
师曰. 换一个 maxOutputBytes; 超过它会取消响应和
掷出 SSHStreamError 有代码 output_limit设置 capture: false 页:1
任意长长输出的边框-记忆流:仍然收到回调
,但结果/错误输出为空并 captured 是虚假的。 捕捉限制
在此模式中被忽略。 无效或超大小的 NDJSON 帧总是被拒绝 .
错误
ExeAPIError数字 :operation和 HTTP 软件status。信息包括: 服务器的错误文本, 在一行, 没有终端逃逸或其他控制 字符,并缩短为200个字符,例如exe.dev API error (422) during ssh: VM "web" is not running永远不会 包括请求,但服务器的文本可以提及您发送的值.error.details().body完全有反应;这可能包含秘密.ExeNetworkError: 在完整答复到来之前,请求失败, 例如网络出错或在读取响应时丢失的连接.operation命名命令,并发送系统错误代码 有一个 操作是否生效未知 :new也许有 创建了 VM,所以通过 aname如果你需要再找到它的话.details().cause有运输错误.ExeProtocolError:不兼容的反应,包括JSON或 不支持 NDJSON SSH 输出的服务器.SSHStreamError:中断/无效输出或捕获限制.code实值interrupted, (中文(简体) ),protocol,或output_limit; 获取器提供捕获的部分 输出。 退出状态不明. 答复前未答复的请求 (例如,网络出错)是interrupted由于命令可能 已经开始了.details()曝光选择性诊断: 服务器的消息或 运输错误.VMReadyError: 准备失败;vm财务报告和审定财务报表cause备有.VMSetupError: 设置脚本失败或未运行cause页:1VMReadyError。 。 。 .
错误无法确定操作从未运行 。 不要盲目重试一个 运输失败后发生突变或远程命令.
认证
通过 SSH 生成一个符号 :
ssh exe.dev ssh-key generate-api-key --label=my-app --exp=30d --cmds="new,ls,ssh,share add,rm"
见 HTTPS API 文档 授权和范围界定.
发展
全体人员 src/ 生成. 编辑 cmd/gensdkjs 及其类型脚本模板
在 exe.dev 仓库中,然后运行 go run ./cmd/gensdkjs 在这里。 复制
输出到此检查和测试中 :
npm install
npm run sync-commands -- ../exe
npm test
npm test 构建软件包,检查公共类型Script API,并运行单元
和现场融合测试。 现场测试需要一个标记的标志 并创建,
复制、执行命令,重新启动、重命名和删除自己的测试 VM.
他们读了 $EXE_TOKEN,或 $EXE_TOKEN_FILE (含
token),或 ~/.config/exedev/sdk-test-token。预期标签是 sdk-test
(与 $EXE_TEST_TAG) (中文(简体) ). 设定 $EXE_BASE_URL 测试另一个
部署,例如 https://exe-staging.dev。要创建测试符号:
ssh exe.dev 'ssh-key generate-api-key --label=sdk-test --tag=sdk-test --exp=30d --cmds="ls,new,whoami,stat,rm,restart,rename,cp,ssh,ssh-key list,share show" --json'
设定 EXE_SKIP_INTEGRATION=1 无法活着进入 设定
EXE_SKIP_SSH_INTEGRATION=1 仅用于在
服务器尚未部署 NDJSON SSH 支持; 这明确跳过 live SSH
和准备状态,而不是相应的单位测试。 现场直播
套接字需要该协议,不会默默地回到原始的SSH输出.
发电机的"去"测试检查再生和命令语法假设. 服务器侧电线合同测试活动创建、上市、复制和SSH. 要运行生成的 SDK 端到端对应本地的 Go HTTP/ SSH 固定 :
# In the exe.dev checkout, with this SDK's npm dependencies installed:
EXE_SDK_JS_DIR=/absolute/path/to/exe-sdk-js go test ./execore -run TestSDKJSHTTP
许可证
麻省理工学院