diff --git a/.gitignore b/.gitignore index 767c889..c83d5d6 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ *.autosave *.swp .DS_Store +config/ Thumbs.db diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..41d4022 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,27 @@ +ARG ALPINE_TAG +FROM alpine:$ALPINE_TAG + +# Install packages. +RUN apk add --no-cache \ + python3 \ + py3-flask \ + py3-flask-pyc \ + py3-gunicorn \ + py3-gunicorn-pyc \ + py3-requests \ + py3-requests-pyc + +# Copy files. +COPY app.py app/ +COPY static/ app/static/ +WORKDIR app + +# Set entrypoint. +ENTRYPOINT [ \ + "gunicorn", \ + "--access-logfile=-", \ + "--bind=0.0.0.0:8000", \ + "--forwarded-allow-ips=*", \ + "--workers=4", \ + "app:app" \ +] diff --git a/README.md b/README.md index 3256962..686ff43 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,44 @@ # librepcb-api-server +Official server-side implementation of the +[LibrePCB API](https://developers.librepcb.org/d1/dcb/doc_server_api.html) +as accessed by the LibrePCB application. Note that some older API paths are +implemented in a different way and might be migrated to this repository +later. + +## Requirements + +Only Docker Compose is needed to run this server on a Linux machine. + +## Configuration + +To make all features working, a configuration file `config/api.json` is +required with the following content: + +```json +{ + /* Config for endpoint '/parts' */ + "parts_operational": false, + "parts_query_url": "", + "parts_query_token": "" +} +``` + +## Usage + +For local development, the server can be run with this command: + +```bash +docker-compose up --build +``` + +Afterwards, the API runs on http://localhost:8000/: + +```bash +curl -X POST -H "Content-Type: application/json" -d @demo-request.json \ + 'http://localhost:8000/api/v1/parts/query' | jq '.' +``` + ## License The content in this repository is published under the diff --git a/app.py b/app.py new file mode 100755 index 0000000..859f50c --- /dev/null +++ b/app.py @@ -0,0 +1,289 @@ +# -*- coding: utf-8 -*- + +import json + +import requests +from flask import (Flask, g, make_response, request, send_from_directory, + url_for) +from werkzeug.middleware.proxy_fix import ProxyFix + +app = Flask(__name__) +app.wsgi_app = ProxyFix(app.wsgi_app, x_proto=1, x_host=1) + +PARTS_MAX_COUNT = 10 +PARTS_QUERY_TIMEOUT = 8.0 +PARTS_QUERY_FRAGMENT = """ + fragment f on Stock { + products { + basic { + manufacturer + mfgpartno + status + } + url + } + summary { + inStockInventory + medianPrice + suppliersInStock + } + } +""" +PARTS_QUERY_STATUS_MAP = { + 'active': 'Active', + 'active-unconfirmed': 'Active', + 'nrfnd': 'NRND', + 'eol': 'Obsolete', + 'obsolete': 'Obsolete', + 'discontinued': 'Obsolete', + 'transferred': 'Obsolete', + 'contact mfr': None, # Not supported, but here to avoid warning. +} +MANUFACTURER_REPLACEMENTS = { + 'ä': 'ae', + 'ö': 'oe', + 'ü': 'ue', + 'texas instruments': 'ti', + 'stmicroelectronics': 'st', +} +MANUFACTURER_REMOVALS = set([ + 'contact', + 'devices', + 'electronics', + 'inc.', + 'inc', + 'incorporated', + 'integrated', + 'international', + 'limited', + 'ltd.', + 'ltd', + 'microelectronics', + 'semiconductor', + 'semiconductors', + 'solutions', + 'systems', + 'technology', + 'usa', +]) + + +def _get_config(key, fallback=None): + if 'config' not in g: + try: + with open('/config/api.json', 'rb') as f: + g.config = json.load(f) + except Exception as e: + app.logger.critical(str(e)) + g.config = dict() + return g.config.get(key, fallback) + + +def _build_headers(): + return { + 'Content-Type': 'application/json', + 'Accept': 'application/json, multipart/mixed', + 'Authorization': 'Bearer {}'.format(_get_config('parts_query_token')), + } + + +def _build_request(parts): + args = [] + queries = [] + variables = {} + for i in range(len(parts)): + args.append('$mpn{}:String!'.format(i)) + queries.append('q{}:findStocks(mfgpartno:$mpn{}){{...f}}'.format(i, i)) + variables['mpn{}'.format(i)] = parts[i]['mpn'] + query = 'query Stocks({}) {{\n{}\n}}'.format( + ','.join(args), + '\n'.join(queries) + ) + PARTS_QUERY_FRAGMENT + return dict(query=query, variables=variables) + + +def _get_basic_value(product, key): + if type(product) is dict: + basic = product.get('basic') + if type(basic) is dict: + value = basic.get(key) + if type(value) is str: + return value + return '' + + +def _normalize_manufacturer(mfr): + mfr = mfr.lower() + for old, new in MANUFACTURER_REPLACEMENTS.items(): + mfr = mfr.replace(old, new) + terms = [s for s in mfr.split(' ') if s not in MANUFACTURER_REMOVALS] + return ' '.join(terms) + + +def _calc_product_match_score(p, mpn_n, mfr_n): + score = 0 + + status_p = PARTS_QUERY_STATUS_MAP.get(_get_basic_value(p, 'status')) + if status_p == 'Active': + score += 200 + elif status_p == 'NRND': + score += 100 + + mpn_p = _get_basic_value(p, 'mfgpartno').lower() + if mpn_p == mpn_n: + score += 20 # MPN matches exactly. + elif mpn_p.replace(' ', '') == mpn_n.replace(' ', ''): + score += 10 # MPN matches when ignoring whitespaces. + else: + return 0 # MPN does not match! + + mfr_p = _normalize_manufacturer(_get_basic_value(p, 'manufacturer')) + if mfr_p == mfr_n: + score += 4 # Manufacturer matches exactly. + elif mfr_n in mfr_p: + score += 3 # Manufacturer matches partially. + elif mfr_n.replace(' ', '') in mfr_p.replace(' ', ''): + score += 2 # Manufacturer matches partially when ignoring whitespaces. + elif mfr_n.split(' ')[0] in mfr_p: + score += 1 # The first term of the manufacturer matches. + else: + return 0 # Manufacturer does not match! + + return score + + +def _get_product(data, mpn, manufacturer): + products = (data.get('products') or []) + for p in products: + p['_score'] = _calc_product_match_score( + p, mpn.lower(), _normalize_manufacturer(manufacturer)) + products = sorted([p for p in products if p['_score'] > 0], + key=lambda p: p['_score'], reverse=True) + return products[0] if len(products) else None + + +def _add_pricing_url(out, data): + value = data.get('url') + if value is not None: + out['pricing_url'] = value + + +def _add_status(out, data): + status = data.get('status') or '' + status_n = status.lower() + value = PARTS_QUERY_STATUS_MAP.get(status_n.lower()) + if value is not None: + out['status'] = value + elif len(status_n) and (status_n not in PARTS_QUERY_STATUS_MAP): + app.logger.warning('Unknown part lifecycle status: {}'.format(status)) + + +def _stock_to_availability(stock): + if stock > 100000: + return 10 # Very Good + elif stock > 5000: + return 5 # Good + elif stock > 200: + return 0 # Normal + elif stock > 0: + return -5 # Bad + else: + return -10 # Very Bad + + +def _suppliers_to_availability(suppliers): + if suppliers > 30: + return 10 # Very Good + elif suppliers > 9: + return 5 # Good + elif suppliers > 1: + return 0 # Normal + elif suppliers > 0: + return -5 # Bad + else: + return -10 # Very Bad + + +def _add_availability(out, data): + stock = data.get('inStockInventory') + suppliers = data.get('suppliersInStock') + values = [] + if type(stock) is int: + values.append(_stock_to_availability(stock)) + if type(suppliers) is int: + values.append(_suppliers_to_availability(suppliers)) + if len(values): + out['availability'] = min(values) + + +def _add_prices(out, summary): + value = summary.get('medianPrice') + if type(value) in [float, int]: + out['prices'] = [dict(quantity=1, price=float(value))] + + +@app.route('/api/v1/parts', methods=['GET']) +def parts(): + enabled = _get_config('parts_operational', False) + response = make_response(dict( + provider_name='Partstack', + provider_url='https://partstack.com', + provider_logo_url=url_for('parts_static', + filename='parts-provider-partstack.png', + _external=True), + info_url='https://api.librepcb.org/api', + query_url=url_for('parts_query', _external=True) if enabled else None, + max_parts=PARTS_MAX_COUNT, + )) + response.headers['Cache-Control'] = 'max-age=300' + return response + + +@app.route('/api/v1/parts/query', methods=['POST']) +def parts_query(): + # Get requested parts. + payload = request.get_json() + parts = payload['parts'][:PARTS_MAX_COUNT] + + # Query parts from information provider. + query_response = requests.post( + _get_config('parts_query_url'), + headers=_build_headers(), + json=_build_request(parts), + timeout=PARTS_QUERY_TIMEOUT, + ) + query_json = query_response.json() + data = query_json.get('data') or {} + errors = query_json.get('errors') or [] + if (len(data) == 0) and (type(query_json.get('message')) is str): + errors.append(query_json['message']) + for error in errors: + app.logger.warning("GraphQL Error: " + str(error)) + + # Convert query response data and return it to the client. + tx = dict(parts=[]) + for i in range(len(parts)): + mpn = parts[i]['mpn'] + manufacturer = parts[i]['manufacturer'] + part_data = data.get('q' + str(i)) or {} + product = _get_product(part_data, mpn, manufacturer) + part = dict( + mpn=mpn, + manufacturer=manufacturer, + results=0 if product is None else 1, + ) + if product is not None: + basic = product.get('basic') or {} + summary = part_data.get('summary') or {} + _add_pricing_url(part, product) + _add_status(part, basic) + _add_availability(part, summary) + _add_prices(part, summary) + tx['parts'].append(part) + return tx + + +@app.route('/api/v1/parts/static/', methods=['GET']) +def parts_static(filename): + return send_from_directory( + 'static', filename, mimetype='image/png', max_age=24*3600) diff --git a/demo-request.json b/demo-request.json new file mode 100644 index 0000000..8b794ab --- /dev/null +++ b/demo-request.json @@ -0,0 +1,8 @@ +{ + "parts": [ + { + "mpn": "1N4148", + "manufacturer": "Vishay" + } + ] +} diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..32150c5 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,17 @@ +version: "3.8" + +services: + server: + build: + context: . + args: + ALPINE_TAG: '3.19' + ports: + - 8000:8000 + volumes: + - './config:/config:ro' + environment: + FLASK_RUN_DEBUG: 1 + FLASK_RUN_HOST: '0.0.0.0' + FLASK_RUN_PORT: 8000 # Same as Gunicorn + entrypoint: ['flask', 'run'] diff --git a/static/parts-provider-librepcb.png b/static/parts-provider-librepcb.png new file mode 100644 index 0000000..2ff2fed Binary files /dev/null and b/static/parts-provider-librepcb.png differ diff --git a/static/parts-provider-partstack.png b/static/parts-provider-partstack.png new file mode 100644 index 0000000..3135677 Binary files /dev/null and b/static/parts-provider-partstack.png differ