@ bumail/ jmap (帮助)

Bun 的 JMAP 服务器: JMAP 核心 (RFC 8620) 和 JMAP 邮件 (RFC 8621),作为一个 阿尔克夏 应用 你骑在自己的。 它服务于任何邮件 @bumail/store MailStore - 同一个商店 @bumail/imap 服务,并阅读信件 @bumail/mime: 会话、 API 与 回历、邮箱、电子邮件和线索, queryChanges,blob下载和上传,以及 事件源推 (RFC 8620§7.3).

bun add @bumail/jmap @alxia/core @bumail/store @bumail/mime

@alxia/core (0.19.0或以后,0.20下), @bumail/store 财务报告和审定财务报表 @bumail/mime 为: 端口: 安装您的应用程序使用的版本 . typescript 是可选的 鼠标,用于类型.

装入Alxia应用软件

jmap(options) 返回 alxia 应用程序。 随你上 plugin: 它添加 GET /.well-known/jmap (届会)和 basePath (单位:千美元)/jmap 以 默认), POST /jmap/api, (中文(简体) ), GET /jmap/download/:accountId/:blobId/:name 财务报告和审定财务报表 POST /jmap/upload/:accountId。其每条路线都认证 ; 您的路线被单独处理.

import { alxia } from '@alxia/core';
import { jmap } from '@bumail/jmap';
import { MemoryMailStore } from '@bumail/store';

const store = new MemoryMailStore();
const alice = await store.createAccount('[email protected]');
await store.createMailbox(alice.id, { name: 'INBOX', role: 'inbox' });

const tokens = new Map([['alice-secret-token', alice.id]]);
const passwords = new Map([['alice', await Bun.password.hash('correct horse')]]);

const server = jmap({
    store,
    origin: 'https://mail.example.com', // the public URL the session's URLs start with
    async authenticate(credentials) {
        if (credentials.scheme === 'bearer') return tokens.get(credentials.token) ?? null;
        const hash = passwords.get(credentials.username);
        if (!hash || !(await Bun.password.verify(credentials.password, hash))) return null;
        return alice.id;
    },
});

const app = alxia()
    .get('/health', ({ reply }) => reply(200, 'ok')) // not authenticated
    .plugin(server);

app.listen(8080);

examples/serve.ts 实值 此示例,可以从克隆中运行 : bun install && bun run build,则 bun packages/jmap/examples/serve.ts,则 curl -H 'Authorization: Bearer alice-secret-token' http://localhost:8080/.well-known/jmap。 。 。 .

认证

authenticate 获得 { scheme: 'basic', username, password } 或者说 { scheme: 'bearer', token },则 Request,则 client数字 : { ip, url },主机应用程序 ctx.ip 财务报告和审定财务报表 originalUrl(ctx) 地址a 登录限制计数 。 它回答 id of the 存储账户以服务,或 null (a) 拒绝(有两项挑战的401项). 它运行在下面 hookTimeout (30 s):投出、悬挂或取名 商店没有的账户是503 onError 被告诉.

Basic仅取自HTTPS. 根据明确要求,法院以 前403页 authenticate 被称为,因为 @bumail/imap 财务报告和审定财务报表 @bumail/smtp 在 TLS 之前拒绝登录。 在结束 TLS 的代理后,声明 主机应用程序上的代理 trustProxy阅读他们说的话:

import { alxia, trustProxy } from '@alxia/core';

const app = alxia({
    proxy: trustProxy({ trusted: ['10.0.0.0/8'], untrusted: 'refuse-all' }),
}).plugin(
    jmap({
        …,
        // the scheme the outermost trusted proxy wrote, never the client's
        secure: (_request, client) => client.url.protocol === 'https:',
        // your own check, its limiter keyed by the forwarded client's address
        authenticate: (credentials, _request, client) => check(credentials, client.ip),
    }),
);

allowInsecureBasic: true 取消拒绝,仅供当地检验。 守护者 任何请求都带有标记.

它的答案是什么

参考文献#ids 与 resultOf, (中文(简体) ), name (单位:千美元) path 与 *(中文(简体) ) 财务报告和审定财务报表 #creationId在一个请求中工作.

上传和下载

// accountId and inboxId come from the session and Mailbox/get; rawMessage is RFC 5322 bytes
const authorization = 'Bearer alice-secret-token';
const upload = await fetch(`https://mail.example.com/jmap/upload/${accountId}`, {
    method: 'POST',
    headers: { authorization, 'content-type': 'message/rfc822' },
    body: rawMessage,
}).then((response) => response.json()); // { accountId, blobId, type, size }

// then: ["Email/import", { accountId, emails: { a: { blobId: upload.blobId, mailboxIds: { [inboxId]: true } } } }, "0"]

下载服务于电子邮件的字节,其一部分(每个部分) blobId 内 Email/get),或上传,与 Range 支持: GET /jmap/download/{accountId}/{blobId}/{name}?accept={type}。 。 。 .

默认上传会活在记忆中. 保持它们恒久,流畅并共享 每个实例,给予 jmap a 一个 UploadStore 从 @bumail/store数字 :

import { SqliteUploadStore } from '@bumail/store/sqlite';

jmap({ store, origin, authenticate, uploads: SqliteUploadStore.open({ directory: '/var/lib/mail' }) });

内容 ttlMs, (中文(简体) ), maxSize 财务报告和审定财务报表 quotaBytes 然后替换 uploadTtl 财务报告和审定财务报表 uploadQuota。它的ID是随机的,所以同样的字节上传两次是两个 上传,每个上行计算在配额上;内存上传会去dupe.

限制

把它们放在下面 limits。 。 。 . maxSizeRequest, (中文(简体) ), maxCallsInRequest, (中文(简体) ), maxConcurrentRequests, (中文(简体) ), maxObjectsInGet, (中文(简体) ), maxObjectsInSet, (中文(简体) ), maxSizeUpload 财务报告和审定财务报表 maxConcurrentUpload 将在会话中宣布 urn:ietf:params:jmap:core 能力。 请求打破的限制是 urn:ietf:params:jmap:error:limit 命名问题( 大小为 413) 派去,429个货币,其余400个, maxSizeResponse 包含; 一个被呼叫中断是一个方法 错误。 药是 [A-Za-z0-9_-]{1,255}; 一个账户永远不会到达另一个账户 账户的数据,无论它名称是什么;错误中重复的客户端文本是 在100个字符后切出.

OpenAPI 文档

包装了它所添加路线的OpenAPI 3.1文件,因为 @bumail/jmap/openapi.json (单位:千美元)openapi/jmap.json 在软件包中:

import document from '@bumail/jmap/openapi.json' with { type: 'json' };

document.paths['/api'].post.operationId; // 'api'

它涵盖会议及其会议反对, POST {basePath}/api 与 请求和答复信封,下载(URI模板) 参数, Range 和上传的《基本》和《坚忍》 rFC 8620 问题 (单位:千美元)notJSON, (中文(简体) ), notRequest, (中文(简体) ), unknownCapability, (中文(简体) ), limit,作为 application/problem+json。API、下载和上传服务器 谁 basePath 变量默认值为 /jmap: 与另一个 basePath设置 变量;路径保持不变.

一个方法调用是 [name, arguments, callId],它的论点是 通用描述, 如 RFC 8620 框框: 命名为 #name 是一种从早先的回复中解开的回溯参照,以及一种方法,即 无法回答 error 在200码内引用 绝对不是HTTP状态. RFC 8620和RFC 8621定义了每种方法的论据. 该文件是 文档和合同:服务器不对其进行验证, 当一个路由和文档有分歧时,包的 spect 失败. 内容 info.version 是文档的版本,而不是软件包的版本.

陷阱

• 搜索存在前所存储的电子邮件在第一次使用时被索引. Email/query 由商店的回答 queryMessages,从搜索 字段中添加电子邮件Email/import 财务报告和审定财务报表 Email/set 传过来. 没有他们的电子邮件最多从其字节读取 maxQueryScan 和田地setSearchFields,没有客户看到; 电话是 serverUnavailable 留下一部分,每一部分 指数增加(绝不是部分结果). Email/queryChanges 拿着 整个结果和答案 requestTooLarge 过去 maxQueryScan 火柴。 比赛. Thread/get 财务报告和审定财务报表 Thread/changes 不扫描: 商店回答它们 . Mailbox/get 计数 unreadEmails, (中文(简体) ), totalThreads 财务报告和审定财务报表 unreadThreads 如RFC 8621 §2所问($seen 在任何拼写读取, $draft 在同一个预算范围内,它的所有邮箱 合计(properties 被弃绝,被弃绝,被弃绝,被弃绝 邮箱的计数是商店的IMAP计数, unseen 对于两个未读 计数和 messages 页:1 totalThreads,这算不上电子邮件 线程,因为商店没有每个邮箱线程数.
• 上传为内存 页:1 uploadTtl,在此过程中 他们,除非 uploads 给出一个 UploadStore:重启会忘记它们,而且 两个进程没有共享.
• sortOrder 总是0和邮箱的 role 无法更改: 商店里没有.
• ifInState 检查,然后调用: 介于 两人没被抓.
• 推是事件源 (RFC 8620 第7.3节):无WebSocket(RFC 8887), 无按键订阅(§7.2)。 溪流逐一地看店铺 pushInterval 何时 notify 他们被称作;他们生活在一个 因此,在几个案例中,只有民意调查才涉及客户,而客户 更改另一个实例.
• 会议在 /.well-known/jmap 上面的应用程序数字 : 挂载 jmap() 在一个没有前缀的应用程序上,或者那个路径也会移动.
• asRaw 显示页眉值 失去他们的领先空间.

推开

GET /jmap/eventsource (届会) eventSourceUrl) 溪流 a StateChange 当一个账户的电子邮件,邮箱,线索,电子邮件交付, 身份或电子邮件 状态动作。 告诉服务器它没有做出修改, 并设置多久一次 寻找其他的pushInterval,以秒计,默认为10:

const server = jmap({ store, origin, authenticate, pushInterval: 5 });
// after a delivery into the store, or an IMAP change:
server.notify(accountId, { delivery: true });
// serving through your own Bun.serve? end the streams before you stop it:
server.close();

API 密码

文档

• 指数:各页,何时读出.
• 指南: 挂起、 认证、 会话、 每一种方法、 以及存储的映射方式, 发送(EmailSubmission 编辑 send hook),blobs,限制,OpenAPI文档,RFCs也随之而来.
• 解决问题: 每一个错误,问题和方法错误,按其准确的文字.
• 路线图:接下来会发生什么——搜索片段,真空响应——和商店漏洞.

许可证

麻省理工学院