89 lines
2.2 KiB
Markdown
89 lines
2.2 KiB
Markdown
# codespace
|
|
|
|
A runnable Go backend MVP skeleton that manages local workspaces, file operations through an abstract filesystem, and OpenCode processes.
|
|
|
|
## V1 scope
|
|
|
|
- Workspace creation, lookup, and deletion backed by local directories.
|
|
- File read/write/list/mkdir/remove/rename/stat through a `FileSystem` interface with path-escape protection.
|
|
- OpenCode process start/stop/restart/status per workspace.
|
|
- HTTP API using [Gin](https://github.com/gin-gonic/gin) for routing with JSON responses.
|
|
- Explicit `http.Server` composition with configurable timeouts and max header bytes.
|
|
|
|
### Not implemented in v1
|
|
|
|
Docker, authentication, Git integration, LSP, AI Agent orchestration, web frontend, and full watcher/WebSocket event streaming are out of scope for the first version.
|
|
|
|
## Run
|
|
|
|
```sh
|
|
make run
|
|
```
|
|
|
|
The server listens on `:8080` by default. Override via `configs/config.yaml` or environment variables:
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `CODESPACE_ADDR` | Listen address |
|
|
| `CODESPACE_WORKSPACE_ROOT` | Workspace root directory |
|
|
| `CODESPACE_OPENCODE_COMMAND` | OpenCode binary path |
|
|
| `CODESPACE_READ_TIMEOUT` | HTTP read timeout (e.g. `15s`) |
|
|
| `CODESPACE_WRITE_TIMEOUT` | HTTP write timeout (e.g. `15s`) |
|
|
| `CODESPACE_IDLE_TIMEOUT` | HTTP idle timeout (e.g. `60s`) |
|
|
| `CODESPACE_MAX_HEADER_BYTES` | Max header bytes (e.g. `1048576`) |
|
|
|
|
## Test
|
|
|
|
```sh
|
|
make test
|
|
```
|
|
|
|
## Configuration
|
|
|
|
`configs/config.yaml`:
|
|
|
|
```yaml
|
|
server:
|
|
addr: ":8080"
|
|
readTimeout: "15s"
|
|
writeTimeout: "15s"
|
|
idleTimeout: "60s"
|
|
maxHeaderBytes: 1048576
|
|
workspace:
|
|
root: "./workspaces"
|
|
process:
|
|
opencodeCommand: "opencode"
|
|
```
|
|
|
|
The server is started through an explicit `http.Server{Handler: router}` — it does not use `gin.Engine.Run()`.
|
|
|
|
## API examples
|
|
|
|
Health check:
|
|
|
|
```sh
|
|
curl -s http://localhost:8080/healthz
|
|
```
|
|
|
|
Create a workspace:
|
|
|
|
```sh
|
|
curl -s -X POST http://localhost:8080/api/workspaces \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"id":"user1"}'
|
|
```
|
|
|
|
Write a file:
|
|
|
|
```sh
|
|
curl -s -X PUT http://localhost:8080/api/workspaces/user1/files/write \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"path":"main.go","content":"package main\n"}'
|
|
```
|
|
|
|
Read a file:
|
|
|
|
```sh
|
|
curl -s 'http://localhost:8080/api/workspaces/user1/files/read?path=main.go'
|
|
```
|