Skip to content

Commit aa1487c

Browse files
grkekgrkek
committed
Update Kramer, add switchable interface
2 parents cfe3c6a + b7c456f commit aa1487c

391 files changed

Lines changed: 38667 additions & 1492 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.ameba.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
Excluded:
22
- repositories/**/*.cr
33

4+
Lint/DebugCalls:
5+
Excluded:
6+
- drivers/**/*_spec.cr
7+
48
# NOTE: These should all be reviewed on an individual basis to see if their
59
# complexity can be reasonably reduced.
610
Metrics/CyclomaticComplexity:

‎.github/workflows/build.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Build and Publish Drivers
2+
on:
3+
push:
4+
branches: [master]
5+
6+
env:
7+
CRYSTAL_VERSION: 1.4.1
8+
9+
jobs:
10+
build:
11+
name: Build
12+
runs-on: ubuntu-latest
13+
environment: Build
14+
steps:
15+
- uses: actions/checkout@v3
16+
17+
# Binary Cache Logic
18+
#############################################################################################
19+
20+
- uses: actions/cache@v3
21+
with:
22+
path: binaries
23+
key: drivers-${{ env.CRYSTAL_VERSION }}-${{ github.run_id }}
24+
restore-keys: drivers-${{ env.CRYSTAL_VERSION }}-
25+
26+
#############################################################################################
27+
28+
- uses: FranzDiebold/github-env-vars-action@v2 # https://github.com/github/feedback/discussions/5251
29+
- name: Build Drivers
30+
run: |
31+
./harness build \
32+
--discover \
33+
--strict-driver-info \
34+
--repository-uri https://github.com/${{ github.repository }} \
35+
--repository-path ./repositories/local \
36+
--ref ${{ github.sha }}
37+
env:
38+
CRYSTAL_VERSION: ${{ env.CRYSTAL_VERSION }}
39+
AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
40+
AWS_SECRET: ${{ secrets.AWS_SECRET }}
41+
AWS_KEY: ${{ secrets.AWS_KEY }}
42+
AWS_REGION: ${{ secrets.AWS_REGION }}

‎.github/workflows/ci.yml‎

Lines changed: 63 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,27 @@ on:
88
schedule:
99
- cron: "0 6 * * 1"
1010

11+
env:
12+
PARALLEL_TESTS: 10
13+
PARALLEL_BUILDS: 2
14+
1115
jobs:
12-
style:
13-
name: "Style"
16+
docs:
17+
if: false # Temporarily disable as docs just _do not work_ for a driver
18+
name: "Crystal Docs"
1419
runs-on: ubuntu-latest
20+
continue-on-error: true
1521
container: crystallang/crystal
1622
steps:
17-
- uses: actions/checkout@v2
18-
- name: Format
19-
run: crystal tool format --check
20-
- name: Lint
21-
uses: crystal-ameba/github-action@v0.2.12
22-
env:
23-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
23+
- uses: actions/checkout@v3
24+
- name: Install Shards
25+
run: shards install --ignore-crystal-version
26+
- name: Docs
27+
run: crystal docs
28+
29+
style:
30+
name: "Style"
31+
uses: PlaceOS/.github/.github/workflows/crystal-style.yml@main
2432

2533
subset-report:
2634
name: "Subset Report - crystal: ${{ matrix.crystal }}, stable: ${{ matrix.stable }}"
@@ -31,7 +39,8 @@ jobs:
3139
matrix:
3240
stable: [true]
3341
crystal:
34-
- 1.0.0
42+
- 1.3.2
43+
- 1.4.1
3544
include:
3645
- stable: false
3746
crystal: nightly
@@ -40,21 +49,29 @@ jobs:
4049
uses: trilom/file-changes-action@v1.2.4
4150
with:
4251
output: ' '
43-
- uses: actions/checkout@v2
52+
- uses: actions/checkout@v3
4453
- name: Cache shards
45-
uses: actions/cache@v2
54+
uses: actions/cache@v3
4655
with:
4756
path: lib
4857
key: ${{ hashFiles('shard.lock') }}
4958
- name: Driver Report
5059
# Skip subset report if dependencies have changed
5160
if: ${{ !contains(steps.changes.outputs.files, 'shard.yml') && !contains(steps.changes.outputs.files, 'shard.lock') }}
52-
run: ./harness report ${{ steps.changes.outputs.files }}
61+
run: |
62+
./harness \
63+
report \
64+
--verbose \
65+
--tests=${{ env.PARALLEL_TESTS }} \
66+
--builds=${{ env.PARALLEL_BUILDS }} \
67+
${{ steps.changes.outputs.files }}
5368
env:
69+
AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
70+
AWS_REGION: ${{ secrets.AWS_REGION }}
5471
CRYSTAL_VERSION: ${{ matrix.crystal }}
5572
- name: Upload failure logs
5673
if: ${{ failure() }}
57-
uses: actions/upload-artifact@v2
74+
uses: actions/upload-artifact@v3
5875
with:
5976
name: logs-${{ matrix.crystal }}-${{ github.sha }}
6077
path: .logs/*.log
@@ -69,24 +86,51 @@ jobs:
6986
matrix:
7087
stable: [true]
7188
crystal:
72-
- 1.0.0
89+
- 1.3.2
90+
- 1.4.1
7391
include:
7492
- stable: false
7593
crystal: nightly
7694
steps:
77-
- uses: actions/checkout@v2
95+
- uses: actions/checkout@v3
96+
7897
- name: Cache shards
79-
uses: actions/cache@v2
98+
uses: actions/cache@v3
8099
with:
81100
path: lib
82101
key: ${{ hashFiles('shard.lock') }}
102+
103+
# Binary Cache Logic
104+
#############################################################################################
105+
106+
- uses: actions/cache@v3
107+
with:
108+
path: binaries
109+
key: drivers-${{ env.CRYSTAL_VERSION }}-${{ github.run_id }}
110+
restore-keys: drivers-${{ env.CRYSTAL_VERSION }}-
111+
112+
#############################################################################################
113+
83114
- name: Driver Report
84-
run: ./harness report
115+
run: |
116+
./harness \
117+
report \
118+
--verbose \
119+
--tests=${{ env.PARALLEL_TESTS }} \
120+
--builds=${{ env.PARALLEL_BUILDS }}
85121
env:
122+
AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
123+
AWS_REGION: ${{ secrets.AWS_REGION }}
86124
CRYSTAL_VERSION: ${{ matrix.crystal }}
125+
- name: Show build container logs
126+
if: ${{ failure() }}
127+
run: docker-compose logs build
128+
- name: Show drivers container logs
129+
if: ${{ failure() }}
130+
run: docker-compose logs drivers
87131
- name: Upload failure logs
88132
if: ${{ failure() }}
89-
uses: actions/upload-artifact@v2
133+
uses: actions/upload-artifact@v3
90134
with:
91135
name: logs-${{ matrix.crystal }}-${{ github.sha }}
92136
path: .logs/*.log

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ app
77
bin
88
doc
99
docs
10+
binaries
1011
lib
1112
.logs
1213
repositories/*
14+
src

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2018 *YOUR COMPANY NAME HERE*
3+
Copyright (c) 2021 Place Technology Limited.
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Command:
1919
report check all drivers' compilation status
2020
up starts the harness
2121
down stops the harness
22+
build builds drivers and uploads them to S3
2223
format formats driver code
2324
help display this message
2425
```
@@ -43,6 +44,16 @@ Before committing, please run...
4344
$ ./harness format
4445
```
4546

47+
## Documentation
48+
49+
- [Writing a PlaceOS Driver](docs/writing-a-driver.md)
50+
- [Testing a PlaceOS Driver](docs/writing-a-spec.md)
51+
- [Sending Emails](docs/guide-event-emails.md)
52+
- [Environment Setup](docs/setup.md)
53+
- [Runtime Debugging](docs/runtime-debugging.md)
54+
- [Directory Structure](docs/directory_structure.md)
55+
- [PlaceOS Spec Runner HTTP API](docs/http-api.md)
56+
4657
## Contributing
4758

4859
1. [Fork it](https://github.com/PlaceOS/drivers/fork)

‎docker-compose.yml‎

Lines changed: 47 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,75 @@
11
version: "3.7"
2+
3+
x-build-client-env: &build-client-env
4+
PLACEOS_BUILD_HOST: ${PLACEOS_BUILD_HOST:-build}
5+
PLACEOS_BUILD_PORT: ${PLACEOS_BUILD_PORT:-3000}
6+
27
services:
38
# Driver test harness
49
drivers:
5-
image: placeos/drivers-spec:crystal-${CRYSTAL_VERSION:-1.0.0}
10+
image: placeos/drivers-spec:latest
611
restart: always
712
container_name: placeos-drivers
813
hostname: drivers
9-
environment:
10-
- CRYSTAL_PATH=lib:/lib/local-shards
1114
depends_on:
15+
- build
1216
- redis
1317
- install-shards
1418
ports:
1519
- 127.0.0.1:8085:8080
1620
- 127.0.0.1:4444:4444
1721
volumes:
18-
- ./.git:/app/.git
19-
- ./.logs:/app/report_failures
20-
- ./drivers:/app/drivers
21-
- ./lib:/app/lib
22-
- ./src:/app/src
23-
- ./repositories:/app/repositories
22+
- ${PWD}/.logs:/app/report_failures
23+
- ${PWD}/repositories:/app/repositories
24+
- ${PWD}:/app/repositories/local
25+
environment:
26+
<<: *build-client-env
27+
CI: ${CI:-}
28+
CRYSTAL_PATH: lib:/lib/local-shards:/usr/share/crystal/src
29+
REDIS_URL: redis://redis:6379
30+
TZ: $TZ
31+
cap_add:
32+
- "SYS_PTRACE"
33+
security_opt:
34+
- "seccomp:unconfined"
35+
36+
build:
37+
image: placeos/build:${PLACE_BUILD_TAG:-latest}
38+
restart: always
39+
hostname: build
40+
volumes:
41+
- ${PWD}/repositories:/app/repositories
42+
- ${PWD}:/app/repositories/local
43+
- ${PWD}/binaries:/app/bin/drivers
2444
environment:
25-
- REDIS_URL=redis://redis:6379
26-
- TZ=$TZ
27-
- CI=${CI:-}
45+
AWS_REGION: ${AWS_REGION:-ap-southeast-2}
46+
AWS_S3_BUCKET: ${AWS_S3_BUCKET:-placeos-drivers}
47+
AWS_KEY: ${AWS_KEY}
48+
AWS_SECRET: ${AWS_SECRET}
49+
GIT_DISCOVERY_ACROSS_FILESYSTEM: 1
50+
PLACEOS_BUILD_LOCAL: 1
51+
PLACEOS_ENABLE_TRACE: 1
52+
TZ: $TZ
2853

2954
redis:
3055
image: eqalpha/keydb
3156
restart: always
3257
hostname: redis
3358
environment:
34-
- TZ=$TZ
59+
TZ: $TZ
3560

3661
# Ensures shards are installed.
3762
install-shards:
38-
image: crystallang/crystal:${CRYSTAL_VERSION:-1.0.0}-alpine
63+
image: placeos/crystal:${CRYSTAL_VERSION:-latest}
3964
restart: "no"
4065
working_dir: /wd
41-
command: ash -c 'shards check -q || shards install'
66+
entrypoint: ''
67+
command: sh -c 'shards check -q || shards install'
4268
environment:
43-
- SHARDS_OPTS="--ignore-crystal-version"
69+
SHARDS_OPTS: "--ignore-crystal-version"
4470
volumes:
45-
- ./shard.lock:/wd/shard.lock
46-
- ./shard.yml:/wd/shard.yml
47-
- ./shard.override.yml:/wd/shard.override.yml
48-
- ./.shards:/wd/.shards
49-
- ./lib:/wd/lib
71+
- ${PWD}/shard.lock:/wd/shard.lock
72+
- ${PWD}/shard.yml:/wd/shard.yml
73+
- ${PWD}/shard.override.yml:/wd/shard.override.yml
74+
- ${PWD}/.shards:/wd/.shards
75+
- ${PWD}/lib:/wd/lib

‎docs/directory_structure.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# Directory Structures
22

3-
PlaceOS core / drivers makes the assumption that the working directory one level
4-
up from the scratch directory. An example deployment structure:
3+
[PlaceOS Core](https://github.com/PlaceOS/core) and [PlaceOS Driver Spec Runner](https://github.com/PlaceOS/driver-spec-runner) make the assumption that the working directory is one level
4+
up from the `drivers` directory.
55

6-
* Working dir: `/home/placeos/core`
6+
An example deployment structure:
7+
8+
* Working directory: `/home/placeos/core`
79
* Executable: `/home/placeos/core/bin/core`
810
* Driver repositories: `/home/placeos/repositories`
911
* PlaceOS Drivers: `/home/placeos/repositories/drivers`
@@ -12,9 +14,10 @@ up from the scratch directory. An example deployment structure:
1214

1315
However when developing the structure will look more like:
1416

15-
* Working dir: `/home/steve/drivers`
16-
* Driver repository: `/home/steve/drivers`
17-
* Driver executables: `/home/steve/drivers/bin/drivers`
17+
* Working directory: `/home/placeos/drivers`
18+
* Driver repository: `/home/placeos/drivers`
19+
* Driver executables: `/home/placeos/drivers/bin/drivers`
1820
* Samsung driver: `/home/placeos/core/bin/drivers/353b53_samsung_display_md_series_cr`
1921

20-
The primary difference between production and development is PlaceOS core, in production, will be cloning repositories and installing shards as required.
22+
The primary difference between production and development is [PlaceOS Core](https://github.com/PlaceOS/core).
23+
In a production environment, PlaceOS Core handles cloning repositories, installing packages, and building Drivers as required.

‎docs/guide-event-emails.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@
22

33
There are three aspects to this
44

5-
1. real-time send an email as soon as an event occurs
6-
2. batching events (either periodically or via a CRON)
7-
3. managing state (state machine management)
5+
1. Sending an email in real-time as an event occurs
6+
2. Batching events (either periodically or via a [CRON](https://crontab.guru/))
7+
3. Managing state (state machine management)
88

9-
i.e. send email straight away if the event is today otherwise send them at 7am every morning and mark emails as sent.
10-
Poll every 15min to send any emails that were missed due to an outage. (by checking state)
9+
For example...
10+
- Send an email straight away if the event is today, otherwise, send them at 7 am every morning and mark the emails as sent.
11+
- Poll every 15min to send any emails that were missed due to an outage (by checking state)
1112

1213

1314
## Example logic driver
@@ -77,7 +78,7 @@ class DeskBookingNotification < PlaceOS::Driver
7778
end
7879
7980
# ensure we don't have two fibers processing this at once
80-
# (technically the driver is thread safe, but it is concurrent)
81+
# (technically the driver is thread-safe, but it is concurrent)
8182
@check_bookings_mutex = Mutex.new
8283
8384
@[Security(Level::Support)]
@@ -435,7 +436,7 @@ email_templates:
435436
Please reach out to your <a
436437
href="mailto:%{support_email}?subject=%{building_name} workplace
437438
question">workplace support team</a> should you have any other queries,
438-
otherwise we look forward to seeing you soon
439+
otherwise, we look forward to seeing you soon
439440
440441
</body></html>
441442

0 commit comments

Comments
 (0)