Console over websocket #124

EmilyxFox · 2025-09-01T17:09:10Z

What

I'm trying to add a websocket console similar to the ssh console that's already there.

This was also requested in itzg/docker-minecraft-server#3152.

Things that currently work:

connect to ws
stream stdout & err over the websocket
send stdin over websocket

Things that don't work

~~sending the last x amount of lines to newly connected clients~~
- Works!
requesting older lines (for scrolling up in a console, for example)
~~websocket isn't gracefully closed by the server before the program exits~~
- ~~closes with 1006~~
- closes with 1001! 🎉

Potential features

itzg/docker-minecraft-server#3152 mentions being able to request things like available commands, auto completions, and various server stats (cpu, ram). I don't know the feasibility of this at all but I thought I'd include it here anyways just to track.

I think being able to query server status (starting, running, stopping) would be cool, or having it sent in a heartbeat type thing.

Why

Feature could be useful for making web panel consoles which I think would be cool as a sidecar.

I think it would also be a good idea to have two formats (json & text) to either use json formatted messages with extra stuff in, or just send plain stdout/err and stdin through the websocket.

I haven't tested a lot of edge cases at all since this code is an absolute mess. I did test the really long line bug though, and it seems to handle that fine. I make no promises that I'll finish this, but I've put it here to gather some feedback :)

remote_shell_service.go

websocket_shell_service.go

itzg

Sorry for the delay reviewing this. Overall, I really like this, especially the new "multi" abstractions.

main.go

websocket_shell_service.go

main.go

remote_shell_service.go

main.go

websocket_shell_service.go

EmilyxFox · 2025-09-06T17:15:01Z

Actually sending stderr works now (tested). I think I should remove the prefix option since its useless with the json output.

EmilyxFox · 2025-09-06T19:02:50Z

@itzg I'd be interested to hear your take on the potential features bit. Especially which ones are kinda doable and which ones are less so.

itzg · 2025-09-06T20:35:11Z

@itzg I'd be interested to hear your take on the potential features bit. Especially which ones are kinda doable and which ones are less so.

It seems like the ones you noted, available commands, auto completions, and various server stats (cpu, ram), are not particularly doable without deeper hooks into with a plugin/mod at which point that plugin/mod should be the one exposing a websocket interface.

My expectations for this websocket support are covered since it can do the equivalent of rcon's sending commands and returning the response. The prior and current logging retrieval was even a bonus/optional capability in my mind.

Reporting server up/down status does seem doable and helpful via a call to mc-monitor.

EmilyxFox · 2025-09-06T20:37:18Z

I think authentication might still be a good idea before its merged. It could just be a header or query param or something like that, I think, and then just taken from the rcon password.

itzg · 2025-09-06T20:39:03Z

Ah, great point about authentication, but yes keeping it simple like leveraging the rcon password as a bearer token, etc seems good.

EmilyxFox · 2025-09-06T22:24:33Z

websocket_shell_service.go

+	password := r.Header.Get("X-WS-Auth")
+	if password != getWebsocketPassword() {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUnauthorized)
+
+		errMsg := AuthErrorMessage{
+			Type:   MessageTypeAuthError,
+			Reason: "invalid password",
+		}
+		json.NewEncoder(w).Encode(errMsg)
+		return
+	}


I would like to be able to skip this with WEBSOCKET_DISABLE_AUTHENTICATION=true but I would have to coerce "true" "TRUE" and maybe "1" to bools and idk you might have a fancy way of doing that.
Otherwise this works. lmk if you don't like the header name or whatnot

I'd recommend adding it to Args like you did the other new field:

https://github.com/itzg/mc-server-runner/pull/124/files#diff-2873f79a86c0d8b3335cd7731b0ecf7dd4301eb19a82ef7a1cba7589b5252261R22

but adding in a WithEnv(""), documented here, in the flags parse call at

https://github.com/itzg/mc-server-runner/pull/124/files#diff-2873f79a86c0d8b3335cd7731b0ecf7dd4301eb19a82ef7a1cba7589b5252261R45

I didn't have to use WithEnv(). That created env vars for every setting and I'm not sure that's what you wanted. lmk!

I forgot that I have a selective way to enable env vars for flags

https://pkg.go.dev/github.com/itzg/go-flagsfiller#:~:text=Conversely%2C%20environment%20variable%20mapping%20can%20be%20enabledper%20field%20with%20%60env:%22name%22%60%20even%20when%20the%20flagsfiller%2Dwide%20option%20was%20not%20included.

websocket_shell_service.go

EmilyxFox · 2025-09-06T22:29:09Z

(I can only reference changes in comments)
I'm wondering if finally closing the websocket just before this done (or maybe after) would be the best place to do it? You'd want to get the whole shutdown sequence sent over the websocket.

itzg · 2025-09-06T22:42:06Z

(I can only reference changes in comments) I'm wondering if finally closing the websocket just before this done (or maybe after) would be the best place to do it? You'd want to get the whole shutdown sequence sent over the websocket.

Yes but even better is to hook into the context that gets cancelled there. Only quirk is that would mean moving the context creation here

https://github.com/itzg/mc-server-runner/pull/124/files#diff-2873f79a86c0d8b3335cd7731b0ecf7dd4301eb19a82ef7a1cba7589b5252261R153

further up and passing that into the websocket server object setup.

I'm likely over simplifying the suggestion so I don't mind pushing a change to show what I mean.

EmilyxFox · 2025-09-06T22:46:21Z

Feel free to push your suggestion. Its quite late here, so no rush, I probably wont write any more code today 🫡

itzg · 2025-10-20T15:10:55Z

(ugh, the UI switched focus on me just before pressing enter)

EmilyxFox · 2025-10-20T15:20:53Z

I thought more about a /console/send endpoint, and think the best way to implement that would be to use RCON locally, and then send the RCON response as the response to the endpoint. I think doing it any other way would be unnecessarily worse than RCON, but then the solution itself seems like a needless abstraction on top of RCON. I think /console for the ws endpoint is still good to allow room for further expansion. If it ends up being the case that a whole internal reverse proxy is needed to route different api requests to different part of the stack, at least this one was separated from the start, and that wont be a breaking change. lmk what you think 😀

edit: i guess needlessness isn't really an argument for why not to do it 🙃
edit2: decided to look up how rcon works and given that it isn't just POSTing to an endpoint, I do think there's utility in abstracting it.

itzg · 2025-10-20T15:32:36Z

Now you've thrown a fun and interesting twist into the discussion: rcon over websocket. Maybe that turns out to be the distinct, portable, and just general enough aspect to focus.

The downside is, that means the docker attach/logs endpoint is probably the better one to shift over for general log consumption.

itzg · 2025-10-20T15:42:00Z

...with that said, that Rcon approach can be iterated later in a separate PR. Don't feel compelled to have this one PR be the end all, last chance 😄

Mqxx · 2025-10-21T06:25:11Z

rcon over websocket

Maybe not RCON over WebSocket but rather RCON over HTTP. Like HTTP POST localhost:8080/console/send and than the command you want to execute on the server. Maybe we could also implement the adapter so that we use the MSMP in the first place for sending commands and fallback to basic RCON for older versions. But yea thats probably out of scope for this PR.

Mqxx · 2025-10-21T06:27:41Z

I think doing it any other way would be unnecessarily worse than RCON, but then the solution itself seems like a needless abstraction on top of RCON.

No abstraction can be worst than RCON itself 😅, also I don't think it would be a "needless abstraction"

Mqxx · 2025-10-21T06:32:04Z

I would suggest, to not get to much out of scope to implement the sending and receiving using only the WebSocket for now with a subpath (/console) and expand that in the future.

apparently failure is more descriptive that its the client's fault and not an error in the auth process

Mqxx · 2025-12-01T21:29:02Z

@EmilyxFox @itzg I cooked something in the meantime: https://github.com/MinecraftPlayground/server-management-mod/wiki

Maybe you can get some inspiration from that.

itzg · 2025-12-02T13:29:13Z

I'm sorry I basically forgot about this PR.

@Mqxx what endpoint are those operations sending to? The ones being added in this PR?

Mqxx · 2025-12-02T13:35:53Z

I'm sorry I basically forgot about this PR.

@Mqxx what endpoint are those operations sending to? The ones being added in this PR?

I used my own:

WS /console/log for log events
POST /console/log for sending commands to the console

I also linked the documentation to the wiki.

Basically the Mod hosts its own HTTP/WS server and you can send/receive to/from it.

itzg · 2025-12-02T13:57:20Z

Sorry, I remember now that yours is a mod based solution.

@EmilyxFox let me know if/how you want to proceed.

Mqxx · 2025-12-02T14:00:26Z

Sorry, I remember now that yours is a mod based solution.

No problem. I figured a mod would be more easy for my use-case. But I also developed a Unix-Socket wrapper for TypeScript: https://jsr.io/@typescriptplayground/socket

But since all of your projects are developed using go or shell, this is probably not that useful for you 😅

EmilyxFox · 2025-12-02T15:23:02Z

Sorry, I remember now that yours is a mod based solution.

@EmilyxFox let me know if/how you want to proceed.

@itzg Probably just a final evaluation and merge if you're happy with it 😁

itzg

Sorry for losing this in the pile. Continues to look great.

itzg · 2025-12-03T22:32:43Z

This is now released in https://github.com/itzg/mc-server-runner/releases/tag/1.14.0

EmilyxFox added 2 commits September 1, 2025 12:58

server to client working

215c905

client to server working

ab518ea

strongdoctor reviewed Sep 2, 2025

View reviewed changes

remote_shell_service.go Outdated Show resolved Hide resolved

strongdoctor reviewed Sep 2, 2025

View reviewed changes

websocket_shell_service.go Outdated Show resolved Hide resolved

strongdoctor reviewed Sep 2, 2025

View reviewed changes

websocket_shell_service.go Outdated Show resolved Hide resolved

deleted cringe

e92b5a5

itzg reviewed Sep 6, 2025

View reviewed changes

EmilyxFox added 8 commits September 6, 2025 18:37

fix unexported variable names

dc5d691

fix passing in context

cd2fc6e

pass in context to echo

7a00724

pass in stderrWriter

ba71baf

remove unused import

943b6c9

better variable names

f09cb4c

put log back in its place

4e2bb91

remove comments

3f77f32

add authentication

34c4e25

EmilyxFox commented Sep 6, 2025

View reviewed changes

websocket_shell_service.go Show resolved Hide resolved

EmilyxFox added 4 commits September 7, 2025 13:23

enable the disabling of authentication 🤓

d2500fd

remove message prefixes

134384c

add error logging to ssh pipe writer

c5b91d0

websocket disable authentication false by default

f9439f5

itzg closed this Oct 20, 2025

itzg reopened this Oct 20, 2025

EmilyxFox added 8 commits October 24, 2025 13:40

make use of args for websocket password

66bc3ef

uniform logging style

f5e4a2b

change struct fields to be more descriptive

57b79bb

change "authErr" to "authFailure"

c437624

apparently failure is more descriptive that its the client's fault and not an error in the auth process

put endpoint on /console

054d559

remove unnecessary time fields

11b5e57

go mod tidy

de722b7

update readme

d392684

EmilyxFox force-pushed the websocket branch from 1c5bb79 to d392684 Compare October 24, 2025 13:43

EmilyxFox added 2 commits October 30, 2025 14:53

don't log stack trace on json parse error

8dccfd9

close with 1001 when server stops

9a63059

itzg approved these changes Dec 3, 2025

View reviewed changes

itzg merged commit b1d2423 into itzg:master Dec 3, 2025

EmilyxFox mentioned this pull request Dec 7, 2025

Bump mc-server-runner & document websocket API itzg/docker-minecraft-server#3789

Merged

Uh oh!

Console over websocket #124

Console over websocket #124

Uh oh!

Conversation

EmilyxFox commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Things that currently work:

Things that don't work

Potential features

Why

Uh oh!

Uh oh!

Uh oh!

Uh oh!

itzg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

EmilyxFox commented Sep 6, 2025

Uh oh!

EmilyxFox commented Sep 6, 2025

Uh oh!

itzg commented Sep 6, 2025

Uh oh!

EmilyxFox commented Sep 6, 2025

Uh oh!

itzg commented Sep 6, 2025

Uh oh!

EmilyxFox Sep 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itzg Sep 6, 2025

Choose a reason for hiding this comment

Uh oh!

EmilyxFox Sep 7, 2025

Choose a reason for hiding this comment

Uh oh!

itzg Sep 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

EmilyxFox commented Sep 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itzg commented Sep 6, 2025

Uh oh!

EmilyxFox commented Sep 6, 2025

Uh oh!

itzg commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EmilyxFox commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itzg commented Oct 20, 2025

Uh oh!

itzg commented Oct 20, 2025

Uh oh!

Mqxx commented Oct 21, 2025

Uh oh!

Mqxx commented Oct 21, 2025

Uh oh!

Mqxx commented Oct 21, 2025

Uh oh!

Mqxx commented Dec 1, 2025

Uh oh!

itzg commented Dec 2, 2025

Uh oh!

Mqxx commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

EmilyxFox commented Sep 1, 2025 •

edited

Loading

EmilyxFox Sep 6, 2025 •

edited

Loading

EmilyxFox commented Sep 6, 2025 •

edited

Loading

itzg commented Oct 20, 2025 •

edited

Loading

EmilyxFox commented Oct 20, 2025 •

edited

Loading

Mqxx commented Dec 2, 2025 •

edited

Loading