# StaticFileService

Serves static files from the device's LittleFS filesystem over HTTP.

## Overview

- Service name: `StaticFileService`
- Mounts: LittleFS at startup
- Endpoints:
  - GET / → serves /index.html
  - GET /* → serves any file under LittleFS by path

Files are looked up relative to the filesystem root. If a requested path is empty or `/`, it falls back to `index.html`. Unknown paths return 404; a helper exists to fall back to `index.html` for SPA routing if desired.

## Content types

Determined by filename extension:

- .html, .htm → text/html
- .css → text/css
- .js → application/javascript
- .json → application/json
- .png → image/png
- .jpg, .jpeg → image/jpeg
- .gif → image/gif
- .svg → image/svg+xml
- .ico → image/x-icon
- default → application/octet-stream

## Building and uploading the filesystem

Place your web assets under the `data/` folder at the project root. The build system packages `data/` into a LittleFS image matching the environment's flash layout.

### Upload via PlatformIO

```bash
# Build and upload filesystem for esp01_1m
pio run -e esp01_1m -t uploadfs

# Build and upload filesystem for d1_mini
pio run -e d1_mini -t uploadfs
```

### Manual image build (optional)

There are helper commands in `ctl.sh` if you need to build and flash the FS image manually:

```bash
# Build image from ./data into littlefs.bin
./ctl.sh mkfs

# Flash image at preconfigured offset
./ctl.sh flashfs
```

Note: Offsets and sizes must match the environment's ldscript. The project defaults are:

- esp01_1m: ldscript `eagle.flash.1m64.ld` (64KB FS)
- d1_mini: ldscript `eagle.flash.4m1m.ld` (1MB FS)

See `docs/Development.md` for details on filesystem and ldscript mapping.

## Enabling the service

`StaticFileService` is registered as a core service in the framework and enabled by default:

```cpp
// part of Spore::registerCoreServices()
auto staticFileService = std::make_shared<StaticFileService>(ctx, apiServer);
services.push_back(staticFileService);
```

If you maintain a custom build without the default services, ensure you instantiate and add the service before starting the API server.

## Routing notes

- Place your SPA assets in `data/` and reference paths relatively.
- To support client-side routing, you can adapt `handleNotFound` to always serve `/index.html` for unknown paths.

## Troubleshooting

- "LittleFS Mount Failed": Ensure `board_build.filesystem = littlefs` is set and the ldscript provides a filesystem region.
- 404 for known files: Confirm the file exists under `data/` and was uploaded (`pio run -t uploadfs`).
- Incorrect MIME type: Add the extension mapping to `getContentType()` if using custom extensions.