xserver

Description:

xserver

xserver #
xserver is a Dart-based web server framework that leverages source generation for automatic handler registration, making it easier to manage and expand your web server's endpoints.
Features #

Automatic Handler Registration: Utilize annotations to auto-register handlers.
Flexible Response Types: Return various response types including Future<T>, Stream<T>, and more.
Type-safe Parameter Handling: Use annotations to handle query parameters, body, headers, and path parameters.
Client Generation: Automatically generate client code for easy API consumption.
Async Context Management: Access the current request context asynchronously with XServer.currentRequest.

Getting Started #
Installation #
Add xserver as a dependency in your pubspec.yaml:
dependencies:
xserver: ^0.2.0
copied to clipboard
Run pub get to install the package.
Usage #
Define the Server
Create a class for your server and annotate it with @xServer.
import 'package:xserver/xserver.dart';

part 'app_server.g.dart';

@xServer
class AppServer extends _$AppServer {
}
copied to clipboard
Define Handlers
Define your handlers within the AppServer class. Use annotations to specify the HTTP method and path.
@xServer
class AppServer extends _$AppServer {
@get
Future<String> test({
@query required String query,
@body required Data body,
@query required int query2,
@header required String header,
@header required int header2,
}) async {
return 'test';
}

@Get('/user/<id>')
Future<String> user(@path String id) async {
return 'User: $id';
}

@Post('/data')
Future<Data> data() async {
return const Data(
query: 'query',
body: 'body',
query2: 1,
header: 'header',
header2: 2,
);
}

@Get('/stream')
Stream<String> stream() async* {
for (var i = 0; i < 100; i++) {
yield 'stream $i';
await Future.delayed(const Duration(seconds: 1));
}
}
}
copied to clipboard
Generate Handlers
Run the build command to generate the handler registration code:
dart run build_runner build
copied to clipboard
Start the Server
You can start the server in your main function:
import 'package:xserver/xserver.dart';

void main() async {
final server = AppServer();
await server.start('localhost', 8080);
print('Server listening on port 8080');
}
copied to clipboard
Handler Annotations #

@All(path): Handles all HTTP methods
@Get(path): Handles GET requests
@Post(path): Handles POST requests

Parameter Annotations #

@Query([name]): Extracts query parameters. If name is omitted, uses the parameter name.
@Body(): Extracts the request body
@Header([name]): Extracts headers. If name is omitted, uses the parameter name.
@Path([name]): Extracts path parameters. If name is omitted, uses the parameter name.

Response Types #
Handlers can return various types:

Future<T>: For asynchronous responses
Stream<T>: For server-sent events or streaming responses
T: For synchronous responses (will be automatically wrapped in a Future)

Where T can be:

String: For text responses
Map<String, dynamic>: For JSON responses
Custom classes with toJson() method: Will be serialized to JSON

Client Generation #
The generator also creates a client class that can be used to make requests to your server:
final client = AppServerClient('http://localhost:8080');
final result = await client.test(
query: 'example',
body: Data(...),
query2: 42,
header: 'some-header',
header2: 123
);
print(result);
copied to clipboard
This client handles serialization and deserialization of requests and responses, making it easy to interact with your server from other parts of your application.
Async Context Management #
xserver uses zoned contexts to manage asynchronous requests. You can access the current request at any time without passing it explicitly:
import 'package:xserver/xserver.dart';

@Get('/example')
Future<String> exampleHandler() async {
final currentRequest = XServer.currentRequest;
// Use the currentRequest as needed
return 'Handled asynchronously!';
}
copied to clipboard
Documentation #
Detailed documentation and examples can be found in the documentation directory.
Contributing #
Contributions are welcome! Please read our contributing guide to get started.
License #
This project is licensed under the MIT License. See the LICENSE file for details.