lino_rest_api

427class AsyncLinoClient(_RequestBuilder):
428    """An asynchronous client for a service that speaks Links Notation."""
429
430    def __init__(
431        self,
432        base_url: str,
433        *,
434        accept: str = DEFAULT_ACCEPT,
435        content_type: str = LINO_CONTENT_TYPE,
436        headers: dict[str, str] | None = None,
437        client: httpx.AsyncClient | None = None,
438        **client_options: Any,
439    ) -> None:
440        """
441        Args:
442            base_url: Base URL of the service
443            accept: ``Accept`` header sent with every request
444            content_type: Representation used for request bodies
445            headers: Headers sent with every request
446            client: ``httpx`` client to use, created when omitted
447            **client_options: Options forwarded to :class:`httpx.AsyncClient`
448        """
449        super().__init__(
450            base_url, accept=accept, content_type=content_type, headers=headers
451        )
452        self._client = client or httpx.AsyncClient(**client_options)
453        self._owns_client = client is None
454
455    async def __aenter__(self) -> "AsyncLinoClient":
456        """Enter a context manager that closes the underlying client."""
457        return self
458
459    async def __aexit__(self, *exception: Any) -> None:
460        """Close the underlying client when it was created here."""
461        await self.aclose()
462
463    async def aclose(self) -> None:
464        """Close the underlying ``httpx`` client when this client owns it."""
465        if self._owns_client:
466            await self._client.aclose()
467
468    async def request(self, method: str, path: str, **options: Any) -> LinoResponse:
469        """
470        Perform a request and decode the response.
471
472        Args:
473            method: HTTP method
474            path: Path, appended to the base URL
475            **options: Request options, see :meth:`_RequestBuilder.prepare`
476
477        Returns:
478            Decoded response
479
480        Raises:
481            LinoClientError: For any 4xx or 5xx response
482        """
483        url, headers, content = self.prepare(path, **options)
484        response = await self._client.request(
485            method, url, headers=headers, content=content
486        )
487        return self.finish(response, method)
488
489    async def get(self, path: str, **options: Any) -> LinoResponse:
490        """
491        ``GET`` a resource.
492
493        Args:
494            path: Path
495            **options: Request options
496
497        Returns:
498            Decoded response
499        """
500        return await self.request("GET", path, **options)
501
502    async def post(
503        self, path: str, body: Any = None, **options: Any
504    ) -> LinoResponse:
505        """
506        ``POST`` to a collection.
507
508        Args:
509            path: Path
510            body: Value to send
511            **options: Request options
512
513        Returns:
514            Decoded response
515        """
516        return await self.request("POST", path, body=body, send_body=True, **options)
517
518    async def put(self, path: str, body: Any = None, **options: Any) -> LinoResponse:
519        """
520        ``PUT`` a representation.
521
522        Args:
523            path: Path
524            body: Value to send
525            **options: Request options
526
527        Returns:
528            Decoded response
529        """
530        return await self.request("PUT", path, body=body, send_body=True, **options)
531
532    async def patch(
533        self, path: str, body: Any = None, **options: Any
534    ) -> LinoResponse:
535        """
536        ``PATCH`` a representation.
537
538        Args:
539            path: Path
540            body: Value to send
541            **options: Request options
542
543        Returns:
544            Decoded response
545        """
546        return await self.request("PATCH", path, body=body, send_body=True, **options)
547
548    async def delete(self, path: str, **options: Any) -> LinoResponse:
549        """
550        ``DELETE`` a resource.
551
552        Args:
553            path: Path
554            **options: Request options
555
556        Returns:
557            Decoded response
558        """
559        return await self.request("DELETE", path, **options)
560
561    async def head(self, path: str, **options: Any) -> LinoResponse:
562        """
563        ``HEAD`` a resource.
564
565        Args:
566            path: Path
567            **options: Request options
568
569        Returns:
570            Decoded response
571        """
572        return await self.request("HEAD", path, **options)
573
574    async def options(self, path: str, **options: Any) -> list[str]:
575        """
576        ``OPTIONS`` a path, returning the advertised methods.
577
578        Args:
579            path: Path
580            **options: Request options
581
582        Returns:
583            Methods listed in ``Allow``
584        """
585        return allowed_methods(await self.request("OPTIONS", path, **options))
586
587    async def list(
588        self, path: str, query: dict[str, Any] | None = None, **options: Any
589    ) -> Any:
590        """
591        List a collection, returning the decoded envelope.
592
593        Args:
594            path: Collection path
595            query: Collection query parameters
596            **options: Request options
597
598        Returns:
599            Collection envelope
600        """
601        return (await self.request("GET", path, query=query, **options)).data
602
603    async def describe(self) -> Any:
604        """
605        Fetch the service description of specification section 9.
606
607        Returns:
608            Description document
609        """
610        return (await self.get(DESCRIPTION_PATH)).data

144class LinoAPI:
145    """
146    LinoAPI class - wraps FastAPI with LINO support.
147
148    Automatically encodes responses as LINO and provides
149    helpers for parsing LINO request bodies.
150    """
151
152    def __init__(
153        self,
154        title: str = "LINO REST API",
155        description: str = "REST API using Links Notation",
156        version: str = "0.1.0",
157        **kwargs,
158    ):
159        """
160        Create a new LinoAPI instance.
161
162        Args:
163            title: API title
164            description: API description
165            version: API version
166            **kwargs: Additional FastAPI arguments
167        """
168        self.app = FastAPI(
169            title=title,
170            description=description,
171            version=version,
172            **kwargs,
173        )
174
175    def get(self, path: str, **kwargs):
176        """
177        Decorator for GET endpoints.
178
179        Args:
180            path: Route path
181            **kwargs: Additional route arguments
182        """
183
184        def decorator(func: Callable) -> Callable:
185            @wraps(func)
186            async def wrapper(request: Request) -> LinoResponse:
187                result = await self._call_handler(func, request)
188                return LinoResponse(content=result)
189
190            self.app.get(path, **kwargs)(wrapper)
191            return func
192
193        return decorator
194
195    def post(self, path: str, **kwargs):
196        """
197        Decorator for POST endpoints.
198
199        Args:
200            path: Route path
201            **kwargs: Additional route arguments
202        """
203
204        def decorator(func: Callable) -> Callable:
205            @wraps(func)
206            async def wrapper(request: Request) -> LinoResponse:
207                result = await self._call_handler(func, request)
208                return LinoResponse(content=result)
209
210            self.app.post(path, **kwargs)(wrapper)
211            return func
212
213        return decorator
214
215    def put(self, path: str, **kwargs):
216        """
217        Decorator for PUT endpoints.
218
219        Args:
220            path: Route path
221            **kwargs: Additional route arguments
222        """
223
224        def decorator(func: Callable) -> Callable:
225            @wraps(func)
226            async def wrapper(request: Request) -> LinoResponse:
227                result = await self._call_handler(func, request)
228                return LinoResponse(content=result)
229
230            self.app.put(path, **kwargs)(wrapper)
231            return func
232
233        return decorator
234
235    def delete(self, path: str, **kwargs):
236        """
237        Decorator for DELETE endpoints.
238
239        Args:
240            path: Route path
241            **kwargs: Additional route arguments
242        """
243
244        def decorator(func: Callable) -> Callable:
245            @wraps(func)
246            async def wrapper(request: Request) -> LinoResponse:
247                result = await self._call_handler(func, request)
248                return LinoResponse(content=result)
249
250            self.app.delete(path, **kwargs)(wrapper)
251            return func
252
253        return decorator
254
255    def patch(self, path: str, **kwargs):
256        """
257        Decorator for PATCH endpoints.
258
259        Args:
260            path: Route path
261            **kwargs: Additional route arguments
262        """
263
264        def decorator(func: Callable) -> Callable:
265            @wraps(func)
266            async def wrapper(request: Request) -> LinoResponse:
267                result = await self._call_handler(func, request)
268                return LinoResponse(content=result)
269
270            self.app.patch(path, **kwargs)(wrapper)
271            return func
272
273        return decorator
274
275    async def _call_handler(self, func: Callable, request: Request) -> Any:
276        """
277        Call a handler function with appropriate arguments.
278
279        Args:
280            func: The handler function
281            request: The FastAPI request
282
283        Returns:
284            Handler result
285        """
286        import inspect
287
288        sig = inspect.signature(func)
289        params = sig.parameters
290
291        kwargs = {}
292
293        for name, _param in params.items():
294            if name == "request":
295                kwargs["request"] = request
296            elif name == "body":
297                kwargs["body"] = await lino_request_handler(request)
298
299        # Check if the function is a coroutine
300        if inspect.iscoroutinefunction(func):
301            return await func(**kwargs)
302        else:
303            return func(**kwargs)
304
305    def get_fastapi_app(self) -> FastAPI:
306        """
307        Get the underlying FastAPI app.
308
309        Returns:
310            FastAPI application instance
311        """
312        return self.app

118class LinoAPIRoute(APIRoute):
119    """
120    Custom APIRoute that automatically uses LINO for responses.
121    """
122
123    def get_route_handler(self) -> Callable:
124        original_handler = super().get_route_handler()
125
126        async def lino_handler(request: Request) -> LinoResponse:
127            response = await original_handler(request)
128
129            # If it's already a LinoResponse, return as-is
130            if isinstance(response, LinoResponse):
131                return response
132
133            # If it's a regular Response, check if we should convert
134            if hasattr(response, "body"):
135                # Already has body, return as-is
136                return response
137
138            # Convert to LinoResponse
139            return LinoResponse(content=response)
140
141        return lino_handler

 98class LinoApp:
 99    """An ASGI application that speaks Links Notation."""
100
101    def __init__(
102        self,
103        *,
104        title: str = "LINO REST API",
105        version: str = "1.0.0",
106        description: str | None = None,
107        cors: bool | dict[str, Any] | None = None,
108        describe: bool = True,
109        supported: list[str] | None = None,
110        max_body_bytes: int = DEFAULT_MAX_BODY_BYTES,
111        expose_traceback: bool = False,
112        default_limit: int | None = None,
113        max_limit: int | None = None,
114    ) -> None:
115        """
116        Args:
117            title: Service title used in the description
118            version: Service version used in the description
119            description: Prose description of the service
120            cors: Enable CORS, optionally with a policy
121            describe: Serve the service description
122            supported: Representations the server may produce
123            max_body_bytes: Largest accepted request body
124            expose_traceback: Attach tracebacks to 5xx problems
125            default_limit: Default collection page size
126            max_limit: Largest collection page size
127        """
128        self.info: dict[str, str] = {"title": title, "version": version}
129        if description:
130            self.info["description"] = description
131        self.cors = cors
132        self.supported = supported
133        self.max_body_bytes = max_body_bytes
134        self.expose_traceback = expose_traceback
135        self.routes = RouteTable()
136        self.handlers: dict[tuple[str, str], Handler] = {}
137
138        self.query_defaults: dict[str, int] = {}
139        if default_limit is not None:
140            self.query_defaults["default_limit"] = default_limit
141        if max_limit is not None:
142            self.query_defaults["max_limit"] = max_limit
143
144        if describe:
145            self._register_description()
146
147    # Registration -----------------------------------------------------------
148
149    def route(
150        self,
151        method: str,
152        path: str,
153        handler: Handler | None = None,
154        meta: dict[str, Any] | None = None,
155    ) -> Registration:
156        """
157        Register a handler for a method and path.
158
159        Given a handler the route is registered and the application returned, so
160        that registrations chain; without one a decorator is returned, so that the
161        handler can be written where it is registered.
162
163        Args:
164            method: HTTP method
165            path: Path pattern, with ``:parameter`` segments
166            handler: Route handler taking a :class:`LinoHttpRequest`
167            meta: Description metadata, for example ``summary``
168
169        Returns:
170            This application, or a decorator when the handler is omitted
171
172        Raises:
173            TypeError: When the method is not one of :data:`HTTP_METHODS`
174        """
175        normalized = method.upper()
176        if normalized not in HTTP_METHODS:
177            raise TypeError(f"Unsupported HTTP method: {method}")
178
179        if handler is None:
180
181            def register(function: Handler) -> Handler:
182                self.route(normalized, path, function, meta)
183                return function
184
185            return register
186
187        self.routes.register(normalized, path, meta)
188        self.handlers[(normalized, path)] = handler
189        return self
190
191    def get(
192        self,
193        path: str,
194        handler: Handler | None = None,
195        meta: dict[str, Any] | None = None,
196    ) -> Registration:
197        """
198        Register a ``GET`` handler.
199
200        Args:
201            path: Path pattern
202            handler: Route handler
203            meta: Description metadata
204
205        Returns:
206            This application, or a decorator when the handler is omitted
207        """
208        return self.route("GET", path, handler, meta)
209
210    def post(
211        self,
212        path: str,
213        handler: Handler | None = None,
214        meta: dict[str, Any] | None = None,
215    ) -> Registration:
216        """
217        Register a ``POST`` handler.
218
219        Args:
220            path: Path pattern
221            handler: Route handler
222            meta: Description metadata
223
224        Returns:
225            This application, or a decorator when the handler is omitted
226        """
227        return self.route("POST", path, handler, meta)
228
229    def put(
230        self,
231        path: str,
232        handler: Handler | None = None,
233        meta: dict[str, Any] | None = None,
234    ) -> Registration:
235        """
236        Register a ``PUT`` handler.
237
238        Args:
239            path: Path pattern
240            handler: Route handler
241            meta: Description metadata
242
243        Returns:
244            This application, or a decorator when the handler is omitted
245        """
246        return self.route("PUT", path, handler, meta)
247
248    def patch(
249        self,
250        path: str,
251        handler: Handler | None = None,
252        meta: dict[str, Any] | None = None,
253    ) -> Registration:
254        """
255        Register a ``PATCH`` handler.
256
257        Args:
258            path: Path pattern
259            handler: Route handler
260            meta: Description metadata
261
262        Returns:
263            This application, or a decorator when the handler is omitted
264        """
265        return self.route("PATCH", path, handler, meta)
266
267    def delete(
268        self,
269        path: str,
270        handler: Handler | None = None,
271        meta: dict[str, Any] | None = None,
272    ) -> Registration:
273        """
274        Register a ``DELETE`` handler.
275
276        Args:
277            path: Path pattern
278            handler: Route handler
279            meta: Description metadata
280
281        Returns:
282            This application, or a decorator when the handler is omitted
283        """
284        return self.route("DELETE", path, handler, meta)
285
286    def resource(self, path: str, store: Any, **options: Any) -> "LinoApp":
287        """
288        Register a CRUD resource, see :func:`lino_rest_api.resource.register_resource`.
289
290        Args:
291            path: Collection path
292            store: Resource store
293            **options: Resource options
294
295        Returns:
296            This application, for chaining
297        """
298        return register_resource(
299            self, path, store, **{**self.query_defaults, **options}
300        )
301
302    def _register_description(self) -> None:
303        """Register the service description routes of specification section 9."""
304        self.get(
305            DESCRIPTION_PATH,
306            lambda request: self.describe(),
307            {"summary": "Service description"},
308        )
309        self.get(
310            OPENAPI_PATH,
311            lambda request: raw_response(
312                json.dumps(self.openapi(), indent=2) + "\n",
313                JSON_CONTENT_TYPE,
314            ),
315            {"summary": "OpenAPI 3.1 description"},
316        )
317
318    # Description ------------------------------------------------------------
319
320    def describe(self) -> dict[str, Any]:
321        """
322        The native service description of specification section 9.
323
324        Returns:
325            Description document
326        """
327        return service_description(self.info, self.routes.describe(), self.supported)
328
329    def openapi(self) -> dict[str, Any]:
330        """
331        The OpenAPI 3.1 rendering of the service description.
332
333        Returns:
334            OpenAPI document
335        """
336        return openapi_document(self.info, self.routes.describe(), self.supported)
337
338    # Request handling -------------------------------------------------------
339
340    async def handle(self, request: LinoHttpRequest) -> ResponseParts:
341        """
342        Run one decoded request through routing and the handler.
343
344        Args:
345            request: Decoded request
346
347        Returns:
348            Response ready to be written
349
350        Raises:
351            LinoHttpError: 404, 405 and anything a handler raises
352        """
353        matched = self.routes.match(request.path)
354        if matched is None:
355            raise LinoHttpError(404, f"No resource at {request.path}")
356
357        entry, params = matched
358        request.params = params
359        allowed = self.routes.allowed_methods(request.path) or []
360
361        method = request.method
362        # HEAD is served by the GET handler with the body dropped, and OPTIONS is
363        # answered from the route table unless a handler claims it.
364        lookup = "GET" if method == "HEAD" and "GET" in entry.methods else method
365
366        if method == "OPTIONS" and "OPTIONS" not in entry.methods:
367            return ResponseParts(204, {"Allow": ", ".join(allowed)}, "")
368
369        if lookup not in entry.methods:
370            raise LinoHttpError(
371                405,
372                f"{method} is not allowed on {request.path}",
373                headers={"Allow": ", ".join(allowed)},
374            )
375
376        handler = self.handlers[(lookup, entry.pattern)]
377        result = handler(request)
378        if inspect.isawaitable(result):
379            result = await result
380
381        if isinstance(result, LinoResult):
382            return build_response(
383                result.value,
384                status=result.status,
385                media_type=result.media_type or request.media_type,
386                headers=result.headers,
387                request_headers=request.headers,
388                method=method,
389                etag=result.etag,
390                preconditions=result.preconditions,
391                require_precondition=result.require_precondition,
392                raw=result.raw,
393            )
394
395        if result is None:
396            return build_response(
397                EMPTY,
398                status=204,
399                media_type=request.media_type,
400                request_headers=request.headers,
401                method=method,
402            )
403
404        return build_response(
405            result,
406            media_type=request.media_type,
407            request_headers=request.headers,
408            method=method,
409        )
410
411    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
412        """
413        ASGI entry point.
414
415        Args:
416            scope: ASGI scope
417            receive: ASGI receive callable
418            send: ASGI send callable
419        """
420        if scope["type"] == "lifespan":
421            await self._lifespan(receive, send)
422            return
423        if scope["type"] != "http":
424            raise NotImplementedError(f"Unsupported scope type: {scope['type']}")
425
426        headers = {
427            name.decode("latin-1").lower(): value.decode("latin-1")
428            for name, value in scope.get("headers", [])
429        }
430        method = scope["method"].upper()
431        path = scope.get("path", "/")
432        query_string = scope.get("query_string", b"").decode("latin-1")
433
434        request = LinoHttpRequest(
435            method=method,
436            path=path,
437            headers=headers,
438            query_string=query_string,
439            scope=scope,
440            app=self,
441        )
442
443        extra_headers = self._cors_headers(headers)
444        preflight = (
445            method == "OPTIONS" and "access-control-request-method" in headers
446        )
447
448        media_type = LINO_CONTENT_TYPE
449        try:
450            if preflight and extra_headers:
451                parts = ResponseParts(204, {}, "")
452            else:
453                media_type = negotiate_request(headers, self.supported)
454                request.media_type = media_type
455                raw = await self._read_body(receive)
456                body, request_media_type = decode_request_body(
457                    raw,
458                    headers.get("content-type"),
459                    max_bytes=self.max_body_bytes,
460                )
461                request.body = body
462                request.request_media_type = request_media_type
463                parts = await self.handle(request)
464        except Exception as error:  # noqa: BLE001 - every error becomes a problem
465            instance = path if not query_string else f"{path}?{query_string}"
466            parts = build_problem_response(
467                error,
468                media_type=media_type,
469                instance=instance,
470                expose_traceback=self.expose_traceback,
471            )
472
473        parts.headers.update(
474            {
475                name: value
476                for name, value in extra_headers.items()
477                if name not in parts.headers
478            }
479        )
480        if extra_headers.get("Access-Control-Allow-Origin", "*") != "*":
481            append_vary(parts.headers, "Origin")
482
483        await self._send(send, parts, head=method == "HEAD")
484
485    async def _lifespan(self, receive: Callable, send: Callable) -> None:
486        """
487        Answer the ASGI lifespan protocol so that servers can start and stop.
488
489        Args:
490            receive: ASGI receive callable
491            send: ASGI send callable
492        """
493        while True:
494            message = await receive()
495            if message["type"] == "lifespan.startup":
496                await send({"type": "lifespan.startup.complete"})
497            elif message["type"] == "lifespan.shutdown":
498                await send({"type": "lifespan.shutdown.complete"})
499                return
500
501    def _cors_headers(self, headers: dict[str, str]) -> dict[str, str]:
502        """
503        Build the CORS response headers for a request.
504
505        Args:
506            headers: Request headers, lower-cased names
507
508        Returns:
509            Response headers ({} when CORS is disabled or the origin is refused)
510        """
511        if not self.cors:
512            return {}
513        return cors_headers(self.cors, headers.get("origin"))
514
515    async def _read_body(self, receive: Callable) -> bytes:
516        """
517        Read the whole request body, refusing oversized payloads early.
518
519        Args:
520            receive: ASGI receive callable
521
522        Returns:
523            Raw request body
524
525        Raises:
526            LinoHttpError: 413 when the body exceeds the configured limit
527        """
528        chunks: list[bytes] = []
529        size = 0
530        while True:
531            message = await receive()
532            if message["type"] == "http.disconnect":
533                break
534            chunks.append(message.get("body", b""))
535            size += len(chunks[-1])
536            if size > self.max_body_bytes:
537                raise LinoHttpError(
538                    413,
539                    f"Request body exceeds {self.max_body_bytes} bytes",
540                    headers={"Connection": "close"},
541                )
542            if not message.get("more_body", False):
543                break
544        return b"".join(chunks)
545
546    async def _send(
547        self, send: Callable, parts: ResponseParts, *, head: bool = False
548    ) -> None:
549        """
550        Write a response to the wire.
551
552        Args:
553            send: ASGI send callable
554            parts: Response to write
555            head: Drop the body, as ``HEAD`` requires
556        """
557        body = parts.body.encode("utf-8")
558        headers = [
559            (name.encode("latin-1"), value.encode("latin-1"))
560            for name, value in parts.headers.items()
561        ]
562        if parts.status not in (204, 304):
563            headers.append((b"content-length", str(len(body)).encode("latin-1")))
564
565        await send(
566            {
567                "type": "http.response.start",
568                "status": parts.status,
569                "headers": headers,
570            }
571        )
572        await send(
573            {"type": "http.response.body", "body": b"" if head else body}
574        )