dgp1130 / bxpb

Browser Extension Protocol Buffer Client/Service Implementation

Howdy folks!

I'm Doug Parker, the "devel without a cause". I'm an overly opinionated software developer on the Angular team at Google. Web development is hard, so I build tooling that makes it easier. I love forcing web tools do things they were never supposed to do.

• Check out my blog with lots of crazy ideas, prototypes, and projects.
• Toot at me on Mastodon at https://techhub.social/@develwithoutacause.
• Check out my GitHub profile at dgp1130.
• Email me at [email protected].
• Historical tweet archive for @develwoutacause.
  • This account has been deactivated on Twitter, but all its tweets are archived here.

bxpb's Issues

Use Solution Style `tsconfig.json` Files

Currently, there are multiple tsconfig.json files, one for normal build, one for test build, and one for the IDE. However, the IDE file is somewhat lying because it assumes that all TypeScript files are available everywhere. For instance, calling Jasmine's describe() from a production file is ok with the IDE but will fail when tsc is called because they are using different configs.

In TypeScript 3.9, a new feature called "solution style" tsconfig files should be able to address this and all the editor to consume all the tsconfig.json files in a reasonable fashion.

MVP

This issue tracks the mainline work to be done to launch minimum viable product (MVP). It gives me somewhere to write down general thoughts and notes that don't necessarily relate to commit messages or markdown docs.

In my view, MVP requires:

• Users can install the compiler as a dev dependency and use it to generate client/service stubs.
  • An ugly/unwieldy command is fine for now.
• Users can implement the service as a simple (req: RequestMessage) => Promise<ResponseMessage>
• Users can call the service with a simple const res = await myService.myMethod(req);.
• Works on latest Chrome with a single message passing API.

Edit: All the major requirements are currently complete, but there are a few cleanup tasks still to do before the 1.0.0 release.

Requirements explicitly not covered by MVP:

• Error handling/propagation.
• Streaming requests or responses.
• Side channel support.
• Builder integration (Webpack, Rollup, Bazel, etc.).
• Proto service co-existing with non-proto service on the same message passing API.
• Multiple proto services on the same message passing API.
• Other browsers/WebExtensions support.
• Development on non-Linux platforms.

Use `@ts-expect-error`

The serve() command should infer types correctly on the service implementation provided by the user. This should fail if a given method is not provided, but that is hard to test in an automated fashion.

Once TS3.9 ships, this should include a @ts-expect-error which can verify that the compiler detected such an error. We should update appropriate usages of @ts-ignore to be @ts-expect-error.

Generate `.ts` files instead of `.d.ts` files

In 7ee936c and #1 (comment), we discovered that hand-writing .d.ts files is a great way to shoot yourself in the foot. Instead, we should generate .ts files and then use tsc to emit .d.ts and .js files from them.

Unfortunately the structure of @bxpb/protoc-plugin as simply a plugin to protoc makes this a little tricky, as we aren't really supposed to edit the actual file system as a tsc compilation would do. I see two potential ways of making this happen:

1. Use typescript as a library in @bxpb/protoc-plugin to create an AST from input source .proto files. Then compile the AST completely in-memory to get an output .js and .d.ts file as simple strings. Those strings can then be returned to protoc to generate the files.
   • I'm not sure how flexible typescript APIs are to perform an in-memory compilation. Module resolution might get weird here.
   • I suspect that we could stub all the filesystem APIs in CompilerHost to read from a virtual file system managed by BXPB (node_modules/ might get tricky here). That might be sufficient to do everything in-memory?
2. Make a temp directory and generate the .ts files there. Then invoke tsc as a subprocess on the directory to generate .js and .d.ts files. Finally, read the output files back to return to protoc so they can be written to the correct location.
   • This gets pretty hacky and is definitely not how protoc plugins are supposed to work.
   • Future Bazel integration may not like this strategy, as you're not supposed to write to undeclared output files.
     • Not sure if Bazel exempts temp directories.
     • If that is a problem, we could handle this at the action level by declaring the temp files and passing them to the BXPB compiler, but this would be a pretty ugly workaround.