Merge pull request #4067 from fbbdev/v3-alpha-feature/service-api

[v3] Built-in service standardisation and enhancement

Author: leaanthony

docs/src/content/docs/changelog.mdx

@@ -64,6 +64,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add cancellable promise wrapper that propagates cancellation requests through promise chains by [@fbbdev](https://github.com/fbbdev) in [#4100](https://github.com/wailsapp/wails/pull/4100)
 - Add the ability to tie binding call cancellation to an `AbortSignal` by [@fbbdev](https://github.com/fbbdev) in [#4100](https://github.com/wailsapp/wails/pull/4100)
 - Support `data-wml-*` attributes for WML alongside the usual `wml-*` attributes by [@leaanthony](https://github.com/leaanthony)
+- Add `Configure` method on all services for late configuration/dynamic reconfiguration by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- `fileserver` service sends a 503 Service Unavailable response when unconfigured by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- `kvstore` service provides an in-memory key-value store by default when unconfigured by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add `Load` method on `kvstore` service to reload data from file after config changes by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add `Clear` method on `kvstore` service to delete all keys by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add type `Level` in `log` service to provide JS-side log-level constants by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add `Log` method on `log` service to specify log-level dynamically by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- `sqlite` service provides an in-memory DB by default when unconfigured by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add method `Close` on `sqlite` service to close the DB manually by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add cancellation support for query methods on `sqlite` service by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Add prepared statement support to `sqlite` service with JS bindings by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
 
 ### Fixed
 
@@ -121,6 +132,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The runtime initialises as soon as it is imported, no need to wait for the window to load by [@fbbdev](https://github.com/fbbdev) in [#4100](https://github.com/wailsapp/wails/pull/4100)
 - The runtime does not export an init method anymore. A side effects import can be used to initialise it by [@fbbdev](https://github.com/fbbdev) in [#4100](https://github.com/wailsapp/wails/pull/4100)
 - Bound methods now return a `CancellablePromise` that rejects with a `CancelError` if cancelled. The actual result of the call is discarded by [@fbbdev](https://github.com/fbbdev) in [#4100](https://github.com/wailsapp/wails/pull/4100)
+- Built-in service types are now consistently called `Service` by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- Built-in service creation functions with options are now consistently called `NewWithConfig` by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
+- `Select` method on `sqlite` service is now named `Query` for consistency with Go APIs by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
 
 ## v3.0.0-alpha.9 - 2025-01-13
 

docs/src/content/docs/learn/services.mdx

@@ -159,14 +159,16 @@ application.NewServiceWithOptions(fileserver.New(&fileserver.Config{
 Let's look at a simplified version of the `fileserver` service as an example:
 
 ```go
+type Config struct {
+    RootPath string
+}
+
 type Service struct {
-    config *Config
-    fs     http.Handler
+    fs http.Handler
 }
 
-func New(config *Config) *Service {
+func NewWithConfig(config *Config) *Service {
     return &Service{
-        config: config,
         fs:     http.FileServer(http.Dir(config.RootPath)),
     }
 }
@@ -175,11 +177,6 @@ func (s *Service) ServiceName() string {
     return "github.com/wailsapp/wails/v3/services/fileserver"
 }
 
-func (s *Service) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
-    // Any initialization code here
-    return nil
-}
-
 func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request) {
     s.fs.ServeHTTP(w, r)
 }

docs/src/content/docs/tutorials/01-creating-a-service.mdx

@@ -40,8 +40,8 @@ This will show you how to organize your code into reusable services and handle e
        return &QRService{}
    }
 
-   // GenerateQRCode creates a QR code from the given text
-   func (s *QRService) GenerateQRCode(text string, size int) ([]byte, error) {
+   // Generate creates a QR code from the given text
+   func (s *QRService) Generate(text string, size int) ([]byte, error) {
        // Generate the QR code
        qr, err := qrcode.New(text, qrcode.Medium)
        if err != nil {
@@ -149,21 +149,21 @@ This will show you how to organize your code into reusable services and handle e
     // This file is automatically generated. DO NOT EDIT
 
     /**
-    * QRService handles QR code generation
-    * @module
-    */
+     * QRService handles QR code generation
+     * @module
+     */
 
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore: Unused imports
     import {Call as $Call, Create as $Create} from "@wailsio/runtime";
 
     /**
-    * GenerateQRCode creates a QR code from the given text
-    * @param {string} text
-    * @param {number} size
-    * @returns {Promise<string> & { cancel(): void }}
-    */
-    export function GenerateQRCode(text, size) {
+     * Generate creates a QR code from the given text
+     * @param {string} text
+     * @param {number} size
+     * @returns {Promise<string> & { cancel(): void }}
+     */
+    export function Generate(text, size) {
         let $resultPromise = /** @type {any} */($Call.ByID(3576998831, text, size));
         let $typingPromise = /** @type {any} */($resultPromise.then(($result) => {
             return $Create.ByteSlice($result);
@@ -173,7 +173,7 @@ This will show you how to organize your code into reusable services and handle e
     }
    ```
 
-    We can see that the bindings are generated for the `GenerateQRCode` method. The parameter names have been preserved,
+    We can see that the bindings are generated for the `Generate` method. The parameter names have been preserved,
     as well as the comments. JSDoc has also been generated for the method to provide type information to your IDE.
 
     :::note
@@ -190,14 +190,36 @@ This will show you how to organize your code into reusable services and handle e
     The bindings generator also supports generating Typescript bindings. You can do this by running `wails3 generate bindings -ts`.
     :::
 
-   <br/>
+    The generated service is re-exported by an `index.js` file:
+
+   ```js title="bindings/changeme/index.js"
+    // @ts-check
+    // Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+    // This file is automatically generated. DO NOT EDIT
+
+    import * as QRService from "./qrservice.js";
+    export {
+        QRService
+    };
+   ```
+
+    You may then access it through the simplified import path
+    `./bindings/changeme` consisting just of your Go package path,
+    without specifying any file name.
+
+    :::note
+    Simplified import paths are only available when using frontend bundlers.
+    If you prefer a vanilla frontend that does not employ a bundler,
+    you will have to import either `index.js` or `qrservice.js` manually.
+    :::
+    <br/>
 
 6. ## Use Bindings in Frontend
 
     Firstly, update `frontend/src/main.js` to use the new bindings:
 
    ```js title="frontend/src/main.js"
-    import { GenerateQRCode } from './bindings/changeme/qrservice.js';
+    import { QRService } from './bindings/changeme';
 
     async function generateQR() {
         const text = document.getElementById('text').value;
@@ -208,7 +230,7 @@ This will show you how to organize your code into reusable services and handle e
 
         try {
             // Generate QR code as base64
-            const qrCodeBase64 = await GenerateQRCode(text, 256);
+            const qrCodeBase64 = await QRService.Generate(text, 256);
 
             // Display the QR code
             const qrDiv = document.getElementById('qrcode');
@@ -285,7 +307,7 @@ This will show you how to organize your code into reusable services and handle e
 
     Type in some text and click the "Generate QR Code" button. You should see a QR code in the center of the page:
 
-   <Image src={qr1} alt="QR Code"/>
+    <Image src={qr1} alt="QR Code"/>
 
     <br/>
     <br/>
@@ -303,13 +325,14 @@ This will show you how to organize your code into reusable services and handle e
     If your service defines Go's standard http handler function `ServeHTTP(w http.ResponseWriter, r *http.Request)`,
     then it can be made accessible on the frontend. Let's extend our QR code service to do this:
 
-    ```go title="qrservice.go" ins={5-6,36-63}
+    ```go title="qrservice.go" ins={4-5,37-65}
     package main
 
     import (
-        "github.com/skip2/go-qrcode"
         "net/http"
         "strconv"
+
+        "github.com/skip2/go-qrcode"
     )
 
     // QRService handles QR code generation
@@ -322,8 +345,8 @@ This will show you how to organize your code into reusable services and handle e
         return &QRService{}
     }
 
-    // GenerateQRCode creates a QR code from the given text
-    func (s *QRService) GenerateQRCode(text string, size int) ([]byte, error) {
+    // Generate creates a QR code from the given text
+    func (s *QRService) Generate(text string, size int) ([]byte, error) {
         // Generate the QR code
         qr, err := qrcode.New(text, qrcode.Medium)
         if err != nil {
@@ -358,7 +381,7 @@ This will show you how to organize your code into reusable services and handle e
         }
 
         // Generate the QR code
-        qrCodeData, err := s.GenerateQRCode(text, size)
+        qrCodeData, err := s.Generate(text, size)
         if err != nil {
             http.Error(w, err.Error(), http.StatusInternalServerError)
             return
@@ -408,11 +431,14 @@ This will show you how to organize your code into reusable services and handle e
     }
    ```
 
+    :::note
+    If you do not set the `Route` option explicitly,
+    the HTTP handler won't be accessible from the frontend.
+    :::
+
     Finally, update `main.js` to make the image source the path to the QR code service, passing the text as a query parameter:
 
     ```js title="frontend/src/main.js"
-    import { GenerateQRCode } from './bindings/changeme/qrservice.js';
-
     async function generateQR() {
         const text = document.getElementById('text').value;
         if (!text) {
@@ -422,7 +448,7 @@ This will show you how to organize your code into reusable services and handle e
 
         const img = document.getElementById('qrcode');
         // Make the image source the path to the QR code service, passing the text
-        img.src = `/qrservice?text=${text}`
+        img.src = `/qrservice?text=${encodeURIComponent(text)}`
     }
 
     export function initializeQRGenerator() {
@@ -440,4 +466,153 @@ This will show you how to organize your code into reusable services and handle e
     <Image src={qr1} alt="QR Code"/>
     <br/>
 
+8. ## Supporting dynamic configurations
+
+    In the example above we used a hardcoded route `/qrservice`.
+    If you edit `main.go` and change the `Route` option without updating `main.js`,
+    the application will break:
+
+    ```go title="main.go" ins={3}
+            // ...
+                application.NewService(NewQRService(), application.ServiceOptions{
+                    Route: "/services/qr",
+                }),
+            // ...
+    ```
+
+    Hardcoded routes can be good for many applications,
+    but if you need more flexibility, method bindings and HTTP handlers
+    can work together to improve the development experience.
+
+    The `ServiceStartup` Lifecycle method provides access to service options at startup,
+    and a custom method can be used to announce the configured route to the frontend.
+
+    First, implement the `ServiceStartup` interface and add a new `URL` method:
+
+    ```go title="qrservice.go" ins={4,6,10,15,23-27,46-55}
+    package main
+
+    import (
+        "context"
+        "net/http"
+        "net/url"
+        "strconv"
+
+        "github.com/skip2/go-qrcode"
+        "github.com/wailsapp/wails/v3/pkg/application"
+    )
+
+    // QRService handles QR code generation
+    type QRService struct {
+        route string
+    }
+
+    // NewQRService creates a new QR service
+    func NewQRService() *QRService {
+        return &QRService{}
+    }
+
+    // ServiceStartup runs at application startup.
+    func (s *QRService) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
+        s.route = options.Route
+        return nil
+    }
+
+    // Generate creates a QR code from the given text
+    func (s *QRService) Generate(text string, size int) ([]byte, error) {
+        // Generate the QR code
+        qr, err := qrcode.New(text, qrcode.Medium)
+        if err != nil {
+            return nil, err
+        }
+
+        // Convert to PNG
+        png, err := qr.PNG(size)
+        if err != nil {
+            return nil, err
+        }
+
+        return png, nil
+    }
+
+    // URL returns an URL that may be used to fetch
+    // a QR code with the given text and size.
+    // It returns an error if the HTTP handler is not available.
+    func (s *QRService) URL(text string, size int) (string, error) {
+        if s.route == "" {
+            return "", errors.New("http handler unavailable")
+        }
+
+        return fmt.Sprintf("%s?text=%s&size=%d", s.route, url.QueryEscape(text), size), nil
+    }
+
+    func (s *QRService) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+        // Extract the text parameter from the request
+        text := r.URL.Query().Get("text")
+        if text == "" {
+            http.Error(w, "Missing 'text' parameter", http.StatusBadRequest)
+            return
+        }
+        // Extract Size parameter from the request
+        sizeText := r.URL.Query().Get("size")
+        if sizeText == "" {
+            sizeText = "256"
+        }
+        size, err := strconv.Atoi(sizeText)
+        if err != nil {
+            http.Error(w, "Invalid 'size' parameter", http.StatusBadRequest)
+            return
+        }
+
+        // Generate the QR code
+        qrCodeData, err := s.Generate(text, size)
+        if err != nil {
+            http.Error(w, err.Error(), http.StatusInternalServerError)
+            return
+        }
+
+        // Write the QR code data to the response
+        w.Header().Set("Content-Type", "image/png")
+        w.Write(qrCodeData)
+    }
+    ```
+
+    Now update `main.js` to use the `URL` method in place of a hardcoded path:
+
+    ```js title="frontend/src/main.js" ins={1,11-12}
+    import { QRService } from "./bindings/changeme";
+
+    async function generateQR() {
+        const text = document.getElementById('text').value;
+        if (!text) {
+            alert('Please enter some text');
+            return;
+        }
+
+        const img = document.getElementById('qrcode');
+        // Invoke the URL method to obtain an URL for the given text.
+        img.src = await QRService.URL(text, 256);
+    }
+
+    export function initializeQRGenerator() {
+        const button = document.getElementById('generateButton');
+        if (button) {
+            button.addEventListener('click', generateQR);
+        } else {
+            console.error('Generate button not found');
+        }
+    }
+    ```
+
+    It should work just like the previous example,
+    but changing the service route in `main.go`
+    will not break the frontend anymore.
+
+    :::note
+    If a Go method returns a non-nil error,
+    the promise on the JS side will reject
+    and await statements will throw an exception.
+    :::
+    <br/>
+
 </Steps>

v3/examples/services/assets/bindings/github.com/wailsapp/wails/v3/pkg/services/kvstore/index.js

@@ -2,7 +2,7 @@
 // Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
 // This file is automatically generated. DO NOT EDIT
 
-import * as KeyValueStore from "./keyvaluestore.js";
+import * as Service from "./service.js";
 export {
-    KeyValueStore
+    Service
 };