cloudscript-server/Readme.md

A local environment for cloudscript development

# Playfab CloudScript Server
A command line program for running your cloudscript code locally  

Has stack traces for Javascript and API errors  
Listens to file changes and restarts the server to reflect the latest changes

## Features
- **Hot Reload**: Automatically restarts server when files change
- **Error Stack Traces**: Detailed error reporting with file and line numbers
- **TypeScript Support**: Generate TypeScript typings for your CloudScript
- **Minification**: Support for minified compilation
- **Remote Execution**: Execute CloudScript on remote servers for better performance
- **Verbose Logging**: Detailed request/response logging
- **Cache Management**: Clear compilation and type generation cache
- **Project Initialization**: Initialize new CloudScript projects

## Installation

First, install the package globally:  
```bash
npm install -g cloudscript-server
```

## Environment Variables

This service requires 2 environment variables:  
- `TITLE_ID` = "your project title id"  
- `TITLE_SECRET` = "your project developer secret"  

You can use a **.env** file in the same cloudscript project folder for setting up the environment variables. Remember to add the **.env** file to the **.gitignore** file for your repository to avoid sensitive keys leaking.

## Basic Usage

Run the program in your cloudscript project directory: 
```bash
cloudscript-server  
```

The default port of the server is **8080**, this can be changed by passing a **-p** or **--port** argument to the program.

You can also use a **-d** or **--dir** argument to point to your cloudscript project folder.

For testing in the editor you have to set in your **PlafabSharedSettings.asset** the **ProductionEnvironmentUrl** to `http://127.0.0.1:8080`.

## Command Line Options

### Server Options
- `-p, --port <number>`: Set server port (default: 8080)
- `-d, --dir <path>`: Set project directory (default: current directory)
- `--minify`: Use minified compilation
- `--verbose`: Enable verbose logging
- `--verboseignore <functions>`: Comma-separated list of functions to ignore in verbose logging
- `--clear-cache, --clearCache`: Clear compilation and type generation cache

### Special Commands
- `init`: Initialize a new CloudScript project
- `clear-cache`: Clear all caches
- `generate-typings, --auto-generate-typings`: Generate TypeScript typings
- `typings`: Generate typings (legacy command)
- `publish`: Publish minified version to PlayFab
- `remote`: Run in remote mode (requires remote server setup)

### Examples
```bash
# Run with custom port and directory
cloudscript-server -p 3000 -d ./my-cloudscript-project

# Run with verbose logging
cloudscript-server --verbose

# Run with minified compilation
cloudscript-server --minify

# Clear cache and run
cloudscript-server --clear-cache

# Initialize new project
cloudscript-server init

# Generate typings
cloudscript-server generate-typings

# Publish to PlayFab
cloudscript-server publish
```

## File Watching

The server automatically watches for changes in `.js` and `.ts` files and restarts when changes are detected. Files in `node_modules` and `typings/autogenerated/` directories are ignored.

## Ignore Files

The CloudScript server supports several ignore files for different purposes:

### .cloudscriptignore
Used during compilation and publishing to exclude files and directories. Uses the same format as `.gitignore`. Default ignored patterns:
```
node_modules
typings
```

### .verboseignore
Used to exclude specific functions from verbose logging. Each function name should be on a separate line.

### .dtsignore
Used to exclude files from TypeScript type generation.

## Project Structure

When you initialize a new project with `cloudscript-server init`, the following structure is created:

```
your-project/
├── .env                    # Environment variables (copy from .env.template)
├── .cloudscriptignore     # Files to ignore during compilation
├── .verboseignore         # Functions to exclude from verbose logging
├── .dtsignore            # Files to exclude from type generation
├── tsconfig.json         # TypeScript configuration
├── ServerUtils.ts        # Server utilities and initialization
└── typings/             # TypeScript type definitions
    └── globals/
        ├── node/
        └── playfab/
```

## Verbose Logging

Enable verbose logging with `--verbose` to see detailed request and response information. You can create a `.verboseignore` file in your project directory to specify functions that should be excluded from verbose logging.

## TypeScript Support

Generate TypeScript typings for your CloudScript:
```bash
cloudscript-server generate-typings
```

This creates type definitions that can be used in your IDE for better development experience.

## Publishing

Publish your CloudScript directly to PlayFab:
```bash
cloudscript-server publish
```

Use a **.cloudscriptignore** file for ignoring files during the publishing process. This file uses the same format as a .gitignore file.

## Remote Server

### Server Setup
This package allows running a WebSocket server to execute the CloudScript file in a remote location for faster responses if the server is located closer to the PlayFab servers (currently: Azure US West 2).

**Server configuration instructions:**  

1. Install docker and docker-compose  
2. Clone this repository in your server  
3. Create a .env file in the same cloudscript-server folder with the following variables:
   ```
   REMOTE_SERVER_DOMAIN = {your_domain}  
   REMOTE_SERVER_AUTH = {a_secret_password}  
   REMOTE_SERVER_PORT = {your_port}  
   ```

4. Run the following commands:
   ```bash
   docker-compose build  
   docker-compose up -d  
   ```

5. Open the port declared above on your server to the internet.

This is a complex feature and can have bugs. If you find any, please report them.  
**Do not, for any reason, run this server in any place where you have sensitive data or any sensitive services due to the nature of remote code execution.**

### Connecting to the Remote Server
In your CloudScript project folder, add the following variables to your .env file:  
```
REMOTE_SERVER_URL = wss://{your_domain}:{your_port}  
REMOTE_SERVER_AUTH = {your_password}  
```

Then run:
```bash
cloudscript-server remote
```

## API Endpoints

The server provides the following endpoints:
- `POST /Client/ExecuteCloudScript`: Execute CloudScript functions (client-side)
- `POST /Server/ExecuteCloudScript`: Execute CloudScript functions (server-side)
- `*`: Proxy all other requests to PlayFab API

## Error Handling

The server provides detailed error information including:
- JavaScript exceptions with stack traces
- PlayFab API errors
- Compilation errors
- Network errors

All errors are logged with colored output for better readability.

## Performance Monitoring

The server tracks:
- API request count
- HTTP request count
- Execution time
- Function logs

This information is included in the response for debugging purposes.

## Disclaimer
This server should not be used in production. It will not work properly because the currentPlayerId is set as a global variable. If a new request arrives while another request is processing, the currentPlayerId will be changed and things will break. In fact, only one user can use this server at a time because of this limitation.

**Important**: When using TypeScript and importing modules, do not use import aliases (like `import {foo as bar} from "module"`). You must use the original variable names in your imports (like `import {foo} from "module"`). Import aliases are not supported during compilation.

Depending on your location and the number of API requests in your handler, this server can be slow due to the higher latency between your location and the PlayFab servers (currently Quincy, Washington).

This package is arriving a little late; it should have been done by PlayFab ages ago, but better late than never...