持久频道公约 0.1.0
此包供同一持久对象实例之内、跨事件之具名文字频道:一事订而阻候,他事布而唤之,订者既醒,乃转发之。云工每 fetch、alarm 之事,皆新造豫言 Wasm 之实例,事与事之间无内存相通,故“甲事候、乙事唤甲”之需(事件流之即时推送、向长联下任务、以回传之片转与正读之调用方),惟借宿主实例内之共享状态而成。此包即于此共享状态之上,予保序、可限时而候、可闭、订数可查之至简接口。接口包惟依标准库。
频道之状,属宿主实例,随持久对象被逐而失:非持久之储,不跨实例,不跨重启。需持久之事列(以供回放)者,用持久事务或关系数据库存之;频道惟司“已发之事之即时告”。此包惟可用于持久对象之事,他事(如常 fetch)调之则抛豫言之异。
频道与订阅
频道以名识之:一至六十四字节,字限 A-Z a-z 0-9 . _ : -,分大小写,不合则抛豫言之异。频道始于首订之现,终于末订之失(取消、关闭、被断)。同一实例之内至多六十四频道,每频道至多二百五十六订:订数逾限,则 订阅持久频道 抛可捕之豫言异(诸事恰同时越限者,后至者或改由宿主拒之);频道数逾限,则宿主拒之,云工今使宿主报误而止本次运行,未必可以「尝试运行」捕之。订乃创之之事所有之资,订阅柄为不透明之串,惟创之之事可用:他事须自订,持他处之柄以调则抛豫言之异。订之后所发者,必达其订;订之前已发者,不补。每订之内,讯保其序:同一发者先发者先至,诸发者交错则视其发之先后。
术
订阅持久频道 订一频道,返订阅柄。订既返,其后所来之讯皆为之排队。
发布持久频道文字 以文发于频道当前诸订,依订之先后而达,返所达之订数;频道不存则返零。文零至六万五千五百三十六字节,空文亦合法;文不得以字节 0xFF 起首(合法 UTF-8 绝不以之起首),违则抛异;逾六万五千五百三十六字节则抛异。已因积压被断之订,不计入所达。
等待持久频道消息 受订阅柄与超时毫秒(零至三百六十万,越界则抛异),阻豫言直至有讯、逾时或订终,返(状态,文):0 得讯,文为讯;1 逾时,文空;2 频道已闭、订因积压逾一 MiB 而被断,或订已被取消,文为其因。超时为零者,立即轮询。状态二之后再候,仍返状态二与同一因。频道闭时,闭前已排队之讯先交,而后得状态二;订因积压被断时,已排队而未读之讯尽弃。阻候之时,不阻他事。
取消订阅持久频道 撤订而释其资,幂等;撤后再候,返(二,订阅已取消)。客当每订配一撤,异常之路亦然。
关闭持久频道 闭一频道:先向诸订交所排之讯,其后各订得状态二与因(至多一千零二十四字节,逾则抛异),返所闭之订数,频道不存则零。闭后同名之频道可复订(新代,与旧订无涉)。
读取持久频道订阅数 返频道今有之订数,不存则零;不改订者候之久暂,亦不生订者可见之讯。
误之类:频道名、大小、时限之域、订阅柄、事类、订数之限等违规者抛豫言之异;逾时、闭、被断、已撤乃可复之业务情形,以候之返状态表之。
先订、后放、再并即时(正用)
事件流之务,欲“联上则先补旧史,再接即时”,而不遗不复。其正法:
一、发者约:先使事持久(得单调递增之序号),后乃发布,讯中带序号;
二、订者先订频道,得订阅柄——自此之后所发者必不失;
三、后读持久之储:最大序号(曰“首”)与 after 之后至首之旧史,放回于客;
四、其后循环候订:讯之序号不逾首者,已在旧史中放过,略之;逾首者转发;
五、将终,撤订。
订前已提而发者,在旧史;订后所提者,自订而收;提于读首之前、发于订之后者,两处皆有,以序号去其重。诸发者并发,则即时之讯所至之次或与序号微异,客当以序号为准。订积压逾一 MiB 则被断:放旧史甚缓或事甚密者,当备得状态二后复订,而自末所转发之序号续之。
限与生命周期
订不随事毕自收(今云工宿主):未撤之订续占其额而受讯,直至积压被断或实例被逐;事因宿主之限或平台之取消而早终者,客亦不及撤。此宿主待改之项(宜于事毕时撤该事所遗之订)。故频道名当取有限之定名,勿以请求号、用户号等无界之量编入名(讯中带号,订者自滤之)。云工每事之豫言实例有墙钟之限(默认三十秒,应用目录之 执行配置.json 可改至多十五分钟);阻候可逾其限,然醒后下一调宿主即败,故候与转之循环当于限内毕。此诸云端之行,除注明本地 workerd 已验者,皆“待云端验证”。
诸宿主一致之要
诸宿主须予同一返值之义与异之类:订后所来者必达、订内保序、所达数之义、状态零、一、二之义与先后、闭时先交而后终、积压断而弃排队之讯、撤之幂等。宿主可异者,惟上限数值之实现之法(不得低于上列之数,或明报之)、内部缓冲与调度。
一致性样例
一、甲事订 c;乙事先后发 a、b,各返一;甲二次候,依次得(零,a)、(零,b)。
二、无订而发,返零;订前所发者不补。
三、甲候二百毫秒而无讯,得(一,空),用时约二百毫秒;其间读订数,不改其久暂。
四、乙以因 收摊 闭 c:甲先收所排之讯,而后得(二,收摊);再候仍(二,收摊);同名可复订。
五、甲订而不读,乙连发逾一 MiB:其后甲之候得(二,含“积压”之因),乙之发不复达甲。
六、同一频道之第二百五十七订,抛可捕之豫言异;第六十五频道,宿主拒之。
七、乙事以甲事之订阅柄调候或撤,抛豫言之异。
八、发零与六万五千五百三十六字节者成;六万五千五百三十七字节者、字节 0xFF 起首者败;频道名不合者败。
九、回放之范:丙事先订,后读首与旧史;丁事于此窗内追加而发若干事;丙之所出,每序号恰现一次。
界
不作持久之储、跨实例之广播、讯之确认或重传、序号之分配、过期、订之过滤与通配、二进制之容、限速;不析其讯;不保事毕自撤订(今);不授网络或存储之能。