use an enum to define job streams

[emilyalbini]

Note: This PR is stacked on top of #100.

---

This PR refactors how we handle job stream names, replacing the string handling we do all over the place with a common JobStream enum. My goal for this is that the compiler should guide you through its errors when adding a new job stream, rather than having to search through the codebase for places where the stream should be handled.

I chose for now to not have the server error out when an unknown stream is received, but that should be an easy change if we want to go for it.

[emilyalbini]

This is the only occurrence of error as a job stream, and nothing else in the codebase handled it. Should this be panic instead?

[jclulow]

The lack of handling in other places is likely just because I've never actually seen it happen in practice. It definitely should not be panic, though; that's for, e.g., kernel panic stacks that occur while your job is running.

I believe we would just have printed with generic debug-ish formatting if it had showed up in a stream, at any rate.

[emilyalbini]

Found another stream we don't handle anywhere else: agent seems to be only used when spawning a job fails. Maybe we should use panic instead? Or task/diag.{name} depending on what failed to spawn?

[jclulow]

This PR refactors how we handle job stream names, replacing the string handling we do all over the place with a common JobStream enum. My goal for this is that the compiler should guide you through its errors when adding a new job stream, rather than having to search through the codebase for places where the stream should be handled.

I'm not sure I would like to go in this direction. I recognise that using the type system has a lot of benefits for some things, but keeping the stream identifiers as strings allows easier gentle evolution, and as I've been adding bits and pieces to the system (e.g., diagnostics, background tasks) the names have started to become more hierarchical, and I don't think the enum scheme here really captures that or allows for as easy an experimental evolution.

[jclulow]

The lack of handling in other places is likely just because I've never actually seen it happen in practice. It definitely should not be panic, though; that's for, e.g., kernel panic stacks that occur while your job is running.

I believe we would just have printed with generic debug-ish formatting if it had showed up in a stream, at any rate.

[emilyalbini]

I recognise that using the type system has a lot of benefits for some things, but keeping the stream identifiers as strings allows easier gentle evolution, and as I've been adding bits and pieces to the system (e.g., diagnostics, background tasks) the names have started to become more hierarchical, and I don't think the enum scheme here really captures that or allows for as easy an experimental evolution.

Could you share a bit more how the enum would prevent experimentation? The server doesn't reject stream names that don't parse as the enum, and all the clients handle unknown streams gracefully. Would changing the layout of the type to better match the hierarchy be better?

enum JobStream {
    Bg {
        name: String,
        stream: BgStream,
    },
    Stdout,
    Stderr,
    ...
}

enum BgStream {
    General,
    Stdout,
    Stderr,
}

[jclulow]

This is an example of something that's different between the string approach, and more rigid enum thing: it's easy and concise to say "paint bg.* regardless of what it is as s_bgtask" in this particular place where we care about that. To represent this subtlety in enums you would presumably have to be able to separate JobStream::Unknown from, say, JobStream::BgUnknown, or JobStream::Background with fields including the ability to preserve the unknown stream name, etc.

It feels like a lot of additional boilerplate in the Rust code to ultimately recreate what's really going on with the strings underneath.

[jclulow]

I think this comment is important to preserve, as regardless of the Rust representation of event streams you'll still need to go and add things to the CSS separately.